@delightui/components 0.1.104 → 0.1.106

package/docs/components/molecules/Accordion.md

@@ -0,0 +1,440 @@
+# Accordion
+
+## Description
+
+A collapsible content component that allows users to expand and collapse sections of information. Supports controlled and uncontrolled modes, custom icons, different sizes, and can be used individually or grouped together for organizing complex content hierarchies.
+
+## Aliases
+
+- Accordion
+- Collapsible
+- Expandable
+- DropDown
+- Disclosure
+
+## Props Breakdown
+
+**Extends:** Standalone interface (no HTML element inheritance)
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `children` | `ReactNode` | - | Yes | Content of the accordion |
+| `size` | `'Small' \| 'Medium' \| 'Large'` | `'Medium'` | No | Size variant of the accordion |
+| `defaultExpanded` | `boolean` | `false` | No | Whether accordion is expanded by default |
+| `expanded` | `boolean` | - | No | Controls expanded state in controlled mode |
+| `onChange` | `(isOpen: boolean) => void` | - | No | Callback when accordion is expanded/collapsed |
+| `name` | `string` | - | No | Unique identifier for the accordion |
+| `className` | `string` | - | No | Additional CSS class names |
+
+**AccordionSummary Props:**
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `children` | `ReactNode` | - | Yes | Header content of the accordion |
+| `expandIcon` | `ReactNode` | - | No | Custom expand/collapse icon |
+| `className` | `string` | - | No | Additional CSS class names |
+
+**AccordionDetails Props:**
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `children` | `ReactNode` | - | Yes | Body content of the accordion |
+| `className` | `string` | - | No | Additional CSS class names |
+
+## Examples
+
+### Basic Usage
+```tsx
+import { Accordion, AccordionSummary, AccordionDetails, Text } from '@delightui/components';
+
+function BasicExample() {
+  return (
+    <Accordion>
+      <AccordionSummary>
+        <Text type="Heading6">What is your return policy?</Text>
+      </AccordionSummary>
+      <AccordionDetails>
+        <Text type="BodyMedium">
+          We offer a 30-day return policy for all items in original condition. 
+          Returns must be initiated within 30 days of purchase.
+        </Text>
+      </AccordionDetails>
+    </Accordion>
+  );
+}
+```
+
+### Multiple Accordions
+```tsx
+function MultipleAccordionsExample() {
+  const faqs = [
+    {
+      id: 1,
+      question: "How do I create an account?",
+      answer: "Click the 'Sign Up' button and fill out the registration form with your email and password."
+    },
+    {
+      id: 2,
+      question: "Can I change my subscription plan?",
+      answer: "Yes, you can upgrade or downgrade your plan at any time from your account settings."
+    },
+    {
+      id: 3,
+      question: "Is my data secure?",
+      answer: "We use industry-standard encryption and security measures to protect your data."
+    }
+  ];
+
+  return (
+    <div className="faq-accordions">
+      {faqs.map(faq => (
+        <Accordion key={faq.id} name={`faq-${faq.id}`}>
+          <AccordionSummary>
+            <Text type="Heading6">{faq.question}</Text>
+          </AccordionSummary>
+          <AccordionDetails>
+            <Text type="BodyMedium">{faq.answer}</Text>
+          </AccordionDetails>
+        </Accordion>
+      ))}
+    </div>
+  );
+}
+```
+
+### Controlled Accordion
+```tsx
+function ControlledAccordionExample() {
+  const [expanded, setExpanded] = useState(false);
+
+  return (
+    <div className="controlled-accordion">
+      <Button onClick={() => setExpanded(!expanded)}>
+        {expanded ? 'Collapse' : 'Expand'} Accordion
+      </Button>
+      
+      <Accordion 
+        expanded={expanded}
+        onChange={setExpanded}
+      >
+        <AccordionSummary>
+          <Text type="Heading6">Controlled Accordion</Text>
+        </AccordionSummary>
+        <AccordionDetails>
+          <Text type="BodyMedium">
+            This accordion's state is controlled by the button above.
+            You can also click on the header to toggle it.
+          </Text>
+        </AccordionDetails>
+      </Accordion>
+    </div>
+  );
+}
+```
+
+### Accordion Sizes
+```tsx
+function AccordionSizesExample() {
+  return (
+    <div className="accordion-sizes">
+      <Accordion size="Small">
+        <AccordionSummary>
+          <Text type="BodyMedium">Small Accordion</Text>
+        </AccordionSummary>
+        <AccordionDetails>
+          <Text type="BodySmall">
+            This is a small accordion with compact spacing.
+          </Text>
+        </AccordionDetails>
+      </Accordion>
+      
+      <Accordion size="Medium">
+        <AccordionSummary>
+          <Text type="Heading6">Medium Accordion</Text>
+        </AccordionSummary>
+        <AccordionDetails>
+          <Text type="BodyMedium">
+            This is a medium accordion with standard spacing.
+          </Text>
+        </AccordionDetails>
+      </Accordion>
+      
+      <Accordion size="Large">
+        <AccordionSummary>
+          <Text type="Heading5">Large Accordion</Text>
+        </AccordionSummary>
+        <AccordionDetails>
+          <Text type="BodyMedium">
+            This is a large accordion with generous spacing.
+          </Text>
+        </AccordionDetails>
+      </Accordion>
+    </div>
+  );
+}
+```
+
+### Custom Icons
+```tsx
+function CustomIconExample() {
+  return (
+    <div className="custom-icon-accordions">
+      <Accordion>
+        <AccordionSummary expandIcon={<Icon icon="Add" />}>
+          <Text type="Heading6">Custom Plus/Minus Icon</Text>
+        </AccordionSummary>
+        <AccordionDetails>
+          <Text type="BodyMedium">
+            This accordion uses a custom plus/minus icon.
+          </Text>
+        </AccordionDetails>
+      </Accordion>
+      
+      <Accordion>
+        <AccordionSummary expandIcon={<Icon icon="ArrowForward" />}>
+          <Text type="Heading6">Arrow Icon</Text>
+        </AccordionSummary>
+        <AccordionDetails>
+          <Text type="BodyMedium">
+            This accordion uses an arrow icon that rotates.
+          </Text>
+        </AccordionDetails>
+      </Accordion>
+    </div>
+  );
+}
+```
+
+### Rich Content Accordion
+```tsx
+function RichContentExample() {
+  return (
+    <Accordion defaultExpanded>
+      <AccordionSummary>
+        <div className="rich-summary">
+          <Icon icon="Settings" />
+          <div className="summary-content">
+            <Text type="Heading6">Account Settings</Text>
+            <Text type="BodySmall">Manage your account preferences</Text>
+          </div>
+          <Chip size="Small" style="A">Pro</Chip>
+        </div>
+      </AccordionSummary>
+      <AccordionDetails>
+        <div className="rich-details">
+          <FormField name="notifications" label="Email Notifications">
+            <Checkbox>Receive email notifications</Checkbox>
+          </FormField>
+          
+          <FormField name="theme" label="Theme Preference">
+            <RadioGroup>
+              <RadioButton value="light">Light Theme</RadioButton>
+              <RadioButton value="dark">Dark Theme</RadioButton>
+              <RadioButton value="auto">Auto</RadioButton>
+            </RadioGroup>
+          </FormField>
+          
+          <FormField name="language" label="Language">
+            <Select>
+              <Option value="en">English</Option>
+              <Option value="es">Spanish</Option>
+              <Option value="fr">French</Option>
+            </Select>
+          </FormField>
+          
+          <ButtonGroup>
+            <Button>Save Changes</Button>
+            <Button type="Outlined">Reset</Button>
+          </ButtonGroup>
+        </div>
+      </AccordionDetails>
+    </Accordion>
+  );
+}
+```
+
+### Nested Accordions
+```tsx
+function NestedAccordionsExample() {
+  return (
+    <Accordion>
+      <AccordionSummary>
+        <Text type="Heading5">Product Categories</Text>
+      </AccordionSummary>
+      <AccordionDetails>
+        <div className="nested-accordions">
+          <Accordion size="Small">
+            <AccordionSummary>
+              <Text type="Heading6">Electronics</Text>
+            </AccordionSummary>
+            <AccordionDetails>
+              <List 
+                data={['Phones', 'Laptops', 'Tablets', 'Accessories']}
+                component={({ item }) => (
+                  <ListItem>
+                    <Text type="BodySmall">{item}</Text>
+                  </ListItem>
+                )}
+              />
+            </AccordionDetails>
+          </Accordion>
+          
+          <Accordion size="Small">
+            <AccordionSummary>
+              <Text type="Heading6">Clothing</Text>
+            </AccordionSummary>
+            <AccordionDetails>
+              <List 
+                data={['Shirts', 'Pants', 'Shoes', 'Accessories']}
+                component={({ item }) => (
+                  <ListItem>
+                    <Text type="BodySmall">{item}</Text>
+                  </ListItem>
+                )}
+              />
+            </AccordionDetails>
+          </Accordion>
+        </div>
+      </AccordionDetails>
+    </Accordion>
+  );
+}
+```
+
+### Accordion Group
+```tsx
+function AccordionGroupExample() {
+  const [openAccordion, setOpenAccordion] = useState(null);
+
+  const handleAccordionChange = (accordionName, isOpen) => {
+    if (isOpen) {
+      setOpenAccordion(accordionName);
+    } else {
+      setOpenAccordion(null);
+    }
+  };
+
+  const sections = [
+    {
+      name: 'getting-started',
+      title: 'Getting Started',
+      content: 'Learn the basics of using our platform.'
+    },
+    {
+      name: 'advanced-features',
+      title: 'Advanced Features',
+      content: 'Explore powerful features for advanced users.'
+    },
+    {
+      name: 'troubleshooting',
+      title: 'Troubleshooting',
+      content: 'Common issues and their solutions.'
+    }
+  ];
+
+  return (
+    <div className="accordion-group">
+      {sections.map(section => (
+        <Accordion
+          key={section.name}
+          name={section.name}
+          expanded={openAccordion === section.name}
+          onChange={(isOpen) => handleAccordionChange(section.name, isOpen)}
+        >
+          <AccordionSummary>
+            <Text type="Heading6">{section.title}</Text>
+          </AccordionSummary>
+          <AccordionDetails>
+            <Text type="BodyMedium">{section.content}</Text>
+          </AccordionDetails>
+        </Accordion>
+      ))}
+    </div>
+  );
+}
+```
+
+### Interactive Accordion
+```tsx
+function InteractiveAccordionExample() {
+  const [activeFeatures, setActiveFeatures] = useState([]);
+
+  const toggleFeature = (feature) => {
+    setActiveFeatures(prev => 
+      prev.includes(feature)
+        ? prev.filter(f => f !== feature)
+        : [...prev, feature]
+    );
+  };
+
+  return (
+    <Accordion>
+      <AccordionSummary>
+        <div className="interactive-summary">
+          <Text type="Heading6">Feature Selection</Text>
+          <Text type="BodySmall">
+            {activeFeatures.length} feature(s) selected
+          </Text>
+        </div>
+      </AccordionSummary>
+      <AccordionDetails>
+        <div className="feature-selection">
+          {['Analytics', 'Reporting', 'API Access', 'Custom Branding'].map(feature => (
+            <FormField key={feature} name={feature}>
+              <Checkbox 
+                checked={activeFeatures.includes(feature)}
+                onValueChange={() => toggleFeature(feature)}
+              >
+                {feature}
+              </Checkbox>
+            </FormField>
+          ))}
+          
+          <Button 
+            disabled={activeFeatures.length === 0}
+            onClick={() => console.log('Selected features:', activeFeatures)}
+          >
+            Apply Features
+          </Button>
+        </div>
+      </AccordionDetails>
+    </Accordion>
+  );
+}
+```
+
+### Loading Accordion
+```tsx
+function LoadingAccordionExample() {
+  const [loading, setLoading] = useState(false);
+  const [content, setContent] = useState(null);
+
+  const loadContent = async () => {
+    setLoading(true);
+    // Simulate API call
+    setTimeout(() => {
+      setContent('This content was loaded dynamically.');
+      setLoading(false);
+    }, 2000);
+  };
+
+  return (
+    <Accordion onChange={(isOpen) => isOpen && !content && loadContent()}>
+      <AccordionSummary>
+        <Text type="Heading6">Dynamic Content</Text>
+        {loading && <Spinner size="Small" />}
+      </AccordionSummary>
+      <AccordionDetails>
+        {loading ? (
+          <div className="loading-content">
+            <Spinner />
+            <Text type="BodyMedium">Loading content...</Text>
+          </div>
+        ) : content ? (
+          <Text type="BodyMedium">{content}</Text>
+        ) : (
+          <Text type="BodyMedium">Click to load content.</Text>
+        )}
+      </AccordionDetails>
+    </Accordion>
+  );
+}
+```