From 4fffd7a3b5b9ac17b12d3b4135622b92d48dff02 Mon Sep 17 00:00:00 2001
From: Andrew Patton <andrew@acusti.ca>
Date: Mon, 8 Jan 2024 15:51:55 -0800
Subject: [PATCH] :memo: Expand and improve Dropdown docs

---
 packages/dropdown/README.md | 73 +++++++++++++++++++++++++++++++++++++
 1 file changed, 73 insertions(+)

diff --git a/packages/dropdown/README.md b/packages/dropdown/README.md
index 8d32349a..8b56edd8 100644
--- a/packages/dropdown/README.md
+++ b/packages/dropdown/README.md
@@ -32,3 +32,76 @@ The three primary design goals for the existence of this component:
        override the minimal default CSS as appropriate
 3. Lightweight bundle size with the bare minimum of dependencies (see
    minzipped size above)
+
+See the [storybook docs and demo][] to get a feel for what it can do.
+
+[storybook docs and demo]:
+    https://acusti-uikit.netlify.app/?path=/docs/uikit-controls-Dropdown--docs
+
+## Usage
+
+```
+npm install @acusti/dropdown
+# or
+yarn add @acusti/dropdown
+```
+
+### Props
+
+This is the type signature for the props you can pass to `Dropdown`. The
+unique features provided by the component are called out and explained
+above the corresponding prop via JSDoc comments:
+
+```ts
+type Props = {
+    /**
+     * Boolean indicating if the user can submit a value not already in the
+     * dropdown.
+     */
+    allowCreate?: boolean;
+    /**
+     * Boolean indicating if the user can submit an empty value (i.e. clear
+     * the value). Defaults to true.
+     */
+    allowEmpty?: boolean;
+    /**
+     * Can take a single React element (e.g. ReactChild) or exactly two
+     * renderable children.
+     */
+    children: React.ReactChild | ChildrenTuple;
+    className?: string;
+    disabled?: boolean;
+    hasItems?: boolean;
+    isOpenOnMount?: boolean;
+    isSearchable?: boolean;
+    keepOpenOnSubmit?: boolean;
+    label?: string;
+    /**
+     * Only usable in conjunction with {isSearchable: true}.
+     * Used as search input’s name.
+     */
+    name?: string;
+    onClick?: (event: React.MouseEvent<HTMLElement>) => unknown;
+    onClose?: () => unknown;
+    onMouseDown?: (event: React.MouseEvent<HTMLElement>) => unknown;
+    onMouseUp?: (event: React.MouseEvent<HTMLElement>) => unknown;
+    onOpen?: () => unknown;
+    onSubmitItem?: (payload: Item) => void;
+    /**
+     * Only usable in conjunction with {isSearchable: true}.
+     * Used as search input’s placeholder.
+     */
+    placeholder?: string;
+    style?: React.CSSProperties;
+    /**
+     * Only usable in conjunction with {isSearchable: true}.
+     * Used as search input’s tabIndex.
+     */
+    tabIndex?: number;
+    /**
+     * Used as search input’s value if props.isSearchable === true
+     * Used to determine if value has changed to avoid triggering onSubmitItem if not
+     */
+    value?: string;
+};
+```