docs: improving collapsible docs

Author: thejackshelton

apps/website/src/components/feature-list/feature-list.tsx

@@ -1,26 +1,32 @@
 import { component$ } from '@builder.io/qwik';
 import { CheckIcon } from '../icons/Check';
 import { Roadmap } from '../icons/Roadmap';
+import { IssueIcon } from '../icons/Issues';
 
 type FeatureListProps = {
   features: string[];
   roadmap?: string[];
+  issues?: string[];
 };
 
 export const FeatureList = component$((props: FeatureListProps) => {
   return (
     <ul class="mb-12 mt-[-16px] !px-0">
-      {props.features.map((descriptor) => {
-        return (
-          <li
-            key={descriptor}
-            class="flex w-full list-none items-center gap-x-2 gap-y-4 border-b-[1px] border-slate-200 py-2 dark:border-slate-800"
-          >
-            <CheckIcon class="min-w-[21px]" />
-            {descriptor}
-          </li>
-        );
-      })}
+      {props.features && (
+        <>
+          {props.features.map((descriptor) => {
+            return (
+              <li
+                key={descriptor}
+                class="flex w-full list-none items-center gap-x-2 gap-y-4 border-b-[1px] border-slate-200 py-2 dark:border-slate-800"
+              >
+                <CheckIcon class="min-w-[21px]" />
+                {descriptor}
+              </li>
+            );
+          })}
+        </>
+      )}
       {props.roadmap && (
         <>
           <h3 class="mb-6 mt-8 scroll-mt-20 text-xl font-semibold">Roadmap</h3>
@@ -39,6 +45,23 @@ export const FeatureList = component$((props: FeatureListProps) => {
           })}
         </>
       )}
+      {props.issues && (
+        <>
+          {props.issues.map((descriptor) => {
+            return (
+              <>
+                <li
+                  key={descriptor}
+                  class="flex w-full list-none items-center gap-x-2 gap-y-4 border-b-[1px] border-slate-200 py-2 dark:border-slate-800"
+                >
+                  <IssueIcon class="min-w-[21px]" />
+                  {descriptor}
+                </li>
+              </>
+            );
+          })}
+        </>
+      )}
     </ul>
   );
 });

apps/website/src/components/icons/Issues.tsx

@@ -0,0 +1,19 @@
+import { PropsOf } from '@builder.io/qwik';
+
+export function IssueIcon(props: PropsOf<'svg'>, key: string) {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width="1.35em"
+      height="1.35em"
+      viewBox="0 0 256 256"
+      {...props}
+      key={key}
+    >
+      <g fill="hsl(var(--alert))">
+        <path d="M224 128a96 96 0 1 1-96-96a96 96 0 0 1 96 96" opacity=".2"></path>
+        <path d="M176 128a8 8 0 0 1-8 8H88a8 8 0 0 1 0-16h80a8 8 0 0 1 8 8m56 0A104 104 0 1 1 128 24a104.11 104.11 0 0 1 104 104m-16 0a88 88 0 1 0-88 88a88.1 88.1 0 0 0 88-88"></path>
+      </g>
+    </svg>
+  );
+}

apps/website/src/routes/docs/headless/collapsible/index.mdx

@@ -48,24 +48,27 @@ An interactive component which expands/collapses a panel.
 
 ## Why use a headless collapsible?
 
-## Animation
+One of the most common questions: _"why not use the native `details` and `summary` HTML elements?"_.
 
-<Showcase name="animation" />
+As much as we love the native elements, they come with a couple of problems:
 
-Follows the WAI-ARIA disclosure pattern.
+### Native element pain points
 
 <FeatureList
-  features={[
-    'Can open by default on SSR (without waking up the component!)',
-    'Does not execute until interaction (including programmatically)',
-    'Does not use any visible tasks',
-    'Automatic animation detection (deprecating the `animated` prop)',
-    `Provides a bind:isOpen prop so that users can open or close it however they'd like (controlled)`,
-    'A `defaultOpen` prop to open it by default (uncontrolled)',
-    'Style based on data states. `initial`, `open`, or `closed`',
+  issues={[
+    'Inconsistent accessibility and browser support',
+    'Inconsistent screen reader support',
+    'Hierarchy and DOM structure restrictions',
+    'Lack of full programmatic control',
   ]}
 />
 
+> To read more about the reasons for implementing an ARIA disclosure widget, check out [Scott O'Hara's article](https://www.scottohara.me/blog/2022/09/12/details-summary.html), as well as the [interactive elements](https://html.spec.whatwg.org/multipage/interactive-elements.html#interactive-elements) section of the HTML spec.
+
+## Animating the content
+
+<Showcase name="animation" />
+
 ## Jack's bug watch 🔎:
 
 <strong style={{ color: 'red' }}>BUG:</strong> Refresh the page and click on programmatic toggle.

apps/website/src/routes/docs/headless/collapsible/snippets/building-blocks.tsx

@@ -3,7 +3,7 @@ import { Collapsible, CollapsibleContent, CollapsibleTrigger } from '@qwik-ui/he
 
 export default component$(() => (
   <Collapsible>
-    <CollapsibleTrigger>Trigger</CollapsibleTrigger>
+    <CollapsibleTrigger>Button</CollapsibleTrigger>
     <CollapsibleContent>Content</CollapsibleContent>
   </Collapsible>
 ));