docs(dropdown): improve docs

docs/src/pages/components/Dropdown.svx

@@ -7,7 +7,9 @@ components: ["Dropdown", "DropdownSkeleton"]
   import Preview from "../../components/Preview.svelte";
 </script>
 
-`Dropdown` is keyed for performance reasons.
+The `Dropdown` component provides a select input with a dropdown menu. It supports
+various states, sizes, and customization options. Each item in the dropdown must
+have a unique `id` property for proper functionality.
 
 <InlineNotification svx-ignore lowContrast title="Note:" kind="info" hideCloseButton>
   <div class="body-short-01">Every <code>items</code> object must have a unique "id" property.</div>
@@ -15,25 +17,33 @@ components: ["Dropdown", "DropdownSkeleton"]
 
 ## Default
 
+Use the `Dropdown` component to create a select input with a dropdown menu. Each item
+must have a unique `id` property.
+
 <Dropdown titleText="Contact" selectedId="0" items="{[{id: "0", text: "Slack"},
   {id: "1", text: "Email"},
   {id: "2", text: "Fax"}]}" />
 
 ## Custom slot
 
-Override the default slot to customize the display of each item. Access the item and index through the `let:` directive.
+Override the default slot to customize the display of each item. Access the item and
+index through the `let:` directive.
 
 <FileSource src="/framed/Dropdown/DropdownSlot" />
 
 ## Hidden label
 
+Hide the label while maintaining accessibility by setting the `hideLabel` prop to
+`true`. The label will still be available to screen readers.
+
 <Dropdown hideLabel titleText="Contact" selectedId="0" items="{[{id: "0", text: "Slack"},
   {id: "1", text: "Email"},
   {id: "2", text: "Fax"}]}" />
 
 ## Format item display text
 
-Use the `itemToString` prop to format the display of individual items.
+Format the display text of items using the `itemToString` prop. This function
+receives the item object and returns the formatted string.
 
 <Dropdown itemToString={item => {
   return item.text + ' (' + item.id +')'
@@ -43,11 +53,15 @@ Use the `itemToString` prop to format the display of individual items.
 
 ## Multiple dropdowns
 
+Create multiple dropdowns that work together. This example demonstrates how to
+manage the state of multiple dropdowns.
+
 <FileSource src="/framed/Dropdown/MultipleDropdown" />
 
 ## Top direction
 
-Set `direction` to `"top"` for the dropdown menu to appear above the input.
+Display the dropdown menu above the input by setting the `direction` prop to
+`"top"`. This is useful when there's limited space below the input.
 
 <Dropdown direction="top" titleText="Contact" selectedId="0" items="{[{id: "0", text: "Slack"},
   {id: "1", text: "Email"},
@@ -55,49 +69,72 @@ Set `direction` to `"top"` for the dropdown menu to appear above the input.
 
 ## Light variant
 
+Use the light variant for dropdowns on dark backgrounds by setting the `light` prop
+to `true`.
+
 <Dropdown light titleText="Contact" selectedId="0" items="{[{id: "0", text: "Slack"},
   {id: "1", text: "Email"},
   {id: "2", text: "Fax"}]}" />
 
 ## Inline variant
 
+Display the dropdown inline with other content by setting the `type` prop to
+`"inline"`. This variant removes the background and border.
+
 <Dropdown type="inline" titleText="Contact" selectedId="0" items="{[{id: "0", text: "Slack"},
   {id: "1", text: "Email"},
   {id: "2", text: "Fax"}]}" />
 
 ## Extra-large size
 
+Increase the size of the dropdown by setting the `size` prop to `"xl"`. This
+provides more visual emphasis for important selections.
+
 <Dropdown size="xl" titleText="Contact" selectedId="0" items="{[{id: "0", text: "Slack"},
   {id: "1", text: "Email"},
   {id: "2", text: "Fax"}]}" />
 
 ## Small size
 
+Decrease the size of the dropdown by setting the `size` prop to `"sm"`. This is
+useful for compact layouts or secondary selections.
+
 <Dropdown size="sm" titleText="Contact" selectedId="0" items="{[{id: "0", text: "Slack"},
   {id: "1", text: "Email"},
   {id: "2", text: "Fax"}]}" />
 
 ## Invalid state
 
+Indicate an invalid selection by setting the `invalid` prop to `true`. Provide
+feedback to users with the `invalidText` prop.
+
 <Dropdown invalid invalidText="Secondary contact method must be different from the primary contact" titleText="Contact" selectedId="0" items="{[{id: "0", text: "Slack"},
   {id: "1", text: "Email"},
   {id: "2", text: "Fax"}]}" />
 
 ## Warning state
 
+Indicate a warning state by setting the `warn` prop to `true`. Provide additional
+context with the `warnText` prop.
+
 <Dropdown warn warnText="This contact method is not associated with your account" titleText="Contact" selectedId="0" items="{[{id: "0", text: "Slack"},
   {id: "1", text: "Email"},
   {id: "2", text: "Fax"}]}" />
 
 ## Disabled state
 
+Disable the entire dropdown by setting the `disabled` prop to `true`. This prevents
+user interaction with the component.
+
 <Dropdown disabled titleText="Contact" selectedId="0" items="{[{id: "0", text: "Slack"},
   {id: "1", text: "Email"},
   {id: "2", text: "Fax"}]}" />
 
 ## Disabled items
 
-Use the `disabled` property in the `items` prop to disable specific items.
+Disable specific items in the dropdown by setting the `disabled` property to
+`true` in the item object. This allows for more granular control over available
+selections.
 
 <Dropdown
   selectedId="0"
@@ -111,4 +148,7 @@ Use the `disabled` property in the `items` prop to disable specific items.
 
 ## Skeleton
 
+Display a loading state using the `DropdownSkeleton` component. This provides
+visual feedback while the dropdown content is being loaded.
+
 <DropdownSkeleton />