From 0bd9004deb9b178371f5bb11903ed326396d253c Mon Sep 17 00:00:00 2001
From: Carlos Filoteo <c.filoteo12@gmail.com>
Date: Mon, 12 Aug 2024 23:19:11 -0600
Subject: [PATCH] Additional docs

---
 src/Accordion/Accordion.stories.tsx       | 18 ++++++++++-
 src/Autocomplete/Autocomplete.stories.tsx | 39 +++++++++++++++++++----
 2 files changed, 49 insertions(+), 8 deletions(-)

diff --git a/src/Accordion/Accordion.stories.tsx b/src/Accordion/Accordion.stories.tsx
index 1027d6d..d3dedc8 100644
--- a/src/Accordion/Accordion.stories.tsx
+++ b/src/Accordion/Accordion.stories.tsx
@@ -22,7 +22,23 @@ export const Default: Story<AccordionProps> = () => {
           HTML Details element
         </a>
         . Some UI requirements, like that in the <em>custom trigger</em> story,
-        make a custom implementation necessary.
+        make a custom implementation necessary. Even a requirement as simple as
+        "animate in/out" might require this.
+      </p>
+      <p>
+        See also:
+        <ul>
+          <li>
+            <a href="https://www.w3.org/TR/wai-aria-practices-1.2/#accordion">
+              WAI-ARIA Accordion Pattern
+            </a>
+          </li>
+          <li>
+            <a href="https://www.w3.org/TR/wai-aria-practices-1.2/#disclosure">
+              WAI-ARIA Disclosure Pattern
+            </a>
+          </li>
+        </ul>
       </p>
       <Accordion>
         <AccordionItemGroup>
diff --git a/src/Autocomplete/Autocomplete.stories.tsx b/src/Autocomplete/Autocomplete.stories.tsx
index 24666c2..30a5970 100644
--- a/src/Autocomplete/Autocomplete.stories.tsx
+++ b/src/Autocomplete/Autocomplete.stories.tsx
@@ -1,19 +1,44 @@
-import type { StoryDefault, Story } from "@ladle/react";
+import type { StoryDefault, Story } from "@ladle/react"
 
-import { Autocomplete, type AutocompleteProps } from "./Autocomplete";
-import { AutocompleteOption } from "./AutocompleteOption";
-import { useState } from "react";
+import { Autocomplete, type AutocompleteProps } from "./Autocomplete"
+import { AutocompleteOption } from "./AutocompleteOption"
+import { useState } from "react"
 
 export default {
   args: {
     autoExpand: true,
   },
-} satisfies StoryDefault<AutocompleteProps>;
+} satisfies StoryDefault<AutocompleteProps>
 
 export const Default: Story<AutocompleteProps> = () => {
-  const [displayValue, setDisplayValue] = useState("");
+  const [displayValue, setDisplayValue] = useState("")
   return (
     <div style={{ minHeight: 250 }}>
+      <p>
+        This Autocomplete was built with the assumption that it might not know
+        what its "options" might look like. Specifically, the use case was to
+        allow for Design/UX to be able to have full flexibility the way the
+        option displayed, as long as the action specified a value on the
+        MenuItem.
+      </p>
+      <p>
+        This implementation also makes use of <code>aria-activedescendant</code>
+        , per{" "}
+        <a href="https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_focus_activedescendant">
+          WAI-ARIA "Managing Focus in Composites Using aria-activedescendant"
+        </a>
+        .
+      </p>
+      <p>
+        See also:
+        <ul>
+          <li>
+            <a href="https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-autocomplete-list/">
+              WAI-ARIA Combobox Example
+            </a>
+          </li>
+        </ul>
+      </p>
       <label htmlFor="demo">Select an option</label>
       <Autocomplete
         id="demo"
@@ -44,4 +69,4 @@ export const Default: Story<AutocompleteProps> = () => {
       </Autocomplete>
     </div>
   )
-};
+}