CollapsibleLayout

The CollapsibleLayout component provides an advanced expandable/collapsible container for React applications. It offers comprehensive features including controlled and uncontrolled state management, multiple animation styles, localStorage persistence, and complete accessibility support.

Features

✅ Dual State Management - Both controlled and uncontrolled usage patterns
✅ Multiple Animations - Fade, slide, and scale transitions with customizable duration
✅ Flexible Triggers - Header click, button only, or both trigger areas
✅ State Persistence - Optional localStorage integration to remember state
✅ Visual Variants - Default, outlined, elevated, and filled styles
✅ Customizable Spacing - Compact, comfortable, and spacious options
✅ Rich Content Support - React nodes and HTML strings for all content areas
✅ Complete Accessibility - WCAG 2.1 AA compliance with keyboard navigation
✅ Data Binding - Full CMS integration through dataSource prop
✅ Theme Integration - Material-UI theming and QwickApp framework support

Basic Usage

import { CollapsibleLayout } from '@qwickapps/react-framework';

function BasicExample() {
  return (
    <CollapsibleLayout
      title="User Settings"
      subtitle="Configure your account preferences"
      defaultCollapsed={false}
    >
      <div>
        <p>This content can be expanded or collapsed by clicking the header.</p>
        <button>Save Settings</button>
      </div>
    </CollapsibleLayout>
  );
}

State Management Patterns

Uncontrolled Component

For most use cases, use uncontrolled mode with defaultCollapsed:

function UncontrolledExample() {
  const handleToggle = (collapsed) => {
    console.log('Layout is now:', collapsed ? 'collapsed' : 'expanded');
  };

  return (
    <CollapsibleLayout
      title="Project Details"
      subtitle="View project information and settings"
      defaultCollapsed={true}
      onToggle={handleToggle}
      variant="outlined"
    >
      <div>
        <h3>Project Configuration</h3>
        <p>Detailed project settings and options...</p>
      </div>
    </CollapsibleLayout>
  );
}

Controlled Component

For external state management, use controlled mode with collapsed:

import { useState } from 'react';

function ControlledExample() {
  const [isCollapsed, setIsCollapsed] = useState(false);
  const [showContent, setShowContent] = useState(true);

  return (
    <div>
      <div style={{ marginBottom: '16px' }}>
        <label>
          <input
            type="checkbox"
            checked={showContent}
            onChange={(e) => setShowContent(e.target.checked)}
          />
          Show content
        </label>
      </div>

      <CollapsibleLayout
        title="Controlled Layout"
        subtitle="State managed by external controls"
        collapsed={!showContent}
        onToggle={(collapsed) => setShowContent(!collapsed)}
        variant="elevated"
      >
        <p>This layout's state is controlled by the checkbox above.</p>
      </CollapsibleLayout>
    </div>
  );
}

Animation Options

Animation Styles

Choose from three built-in animation styles:

function AnimationExamples() {
  return (
    <div>
      {/* Fade animation - smooth opacity transition */}
      <CollapsibleLayout
        title="Fade Animation"
        animationStyle="fade"
        animationDuration={300}
        defaultCollapsed={true}
      >
        <p>Content fades in and out smoothly</p>
      </CollapsibleLayout>

      {/* Slide animation (default) - height-based transition */}
      <CollapsibleLayout
        title="Slide Animation"
        animationStyle="slide"
        animationDuration={300}
        defaultCollapsed={true}
      >
        <p>Content slides up and down</p>
      </CollapsibleLayout>

      {/* Scale animation - combines scaling and fading */}
      <CollapsibleLayout
        title="Scale Animation"
        animationStyle="scale"
        animationDuration={200}
        defaultCollapsed={true}
      >
        <p>Content scales and fades for dynamic effect</p>
      </CollapsibleLayout>
    </div>
  );
}

Custom Animation Duration

function CustomDurationExample() {
  return (
    <div>
      <CollapsibleLayout
        title="Fast Animation (150ms)"
        animationDuration={150}
        defaultCollapsed={true}
      >
        <p>Quick, snappy transitions</p>
      </CollapsibleLayout>

      <CollapsibleLayout
        title="Slow Animation (800ms)"
        animationDuration={800}
        defaultCollapsed={true}
      >
        <p>Deliberate, dramatic transitions</p>
      </CollapsibleLayout>

      {/* Disable animations entirely */}
      <CollapsibleLayout
        title="No Animation"
        disableAnimations={true}
        defaultCollapsed={true}
      >
        <p>Instant show/hide with no transition</p>
      </CollapsibleLayout>
    </div>
  );
}

Visual Variants

Container Variants

function VariantExamples() {
  return (
    <div>
      {/* Default - minimal styling */}
      <CollapsibleLayout
        title="Default Variant"
        variant="default"
        defaultCollapsed={false}
      >
        <p>Clean, minimal appearance</p>
      </CollapsibleLayout>

      {/* Outlined - subtle border */}
      <CollapsibleLayout
        title="Outlined Variant"
        variant="outlined"
        defaultCollapsed={false}
      >
        <p>Defined with border outline</p>
      </CollapsibleLayout>

      {/* Elevated - shadow effect */}
      <CollapsibleLayout
        title="Elevated Variant"
        variant="elevated"
        defaultCollapsed={false}
      >
        <p>Lifted appearance with shadow</p>
      </CollapsibleLayout>

      {/* Filled - background color */}
      <CollapsibleLayout
        title="Filled Variant"
        variant="filled"
        defaultCollapsed={false}
      >
        <p>Emphasized with background</p>
      </CollapsibleLayout>
    </div>
  );
}

Spacing Options

function SpacingExamples() {
  return (
    <div>
      {/* Compact - minimal padding */}
      <CollapsibleLayout
        title="Compact Layout"
        headerSpacing="compact"
        contentSpacing="compact"
        variant="outlined"
      >
        <p>Dense layout for space-constrained interfaces</p>
      </CollapsibleLayout>

      {/* Comfortable (default) - balanced padding */}
      <CollapsibleLayout
        title="Comfortable Layout"
        headerSpacing="comfortable"
        contentSpacing="comfortable"
        variant="outlined"
      >
        <p>Standard spacing for most applications</p>
      </CollapsibleLayout>

      {/* Spacious - generous padding */}
      <CollapsibleLayout
        title="Spacious Layout"
        headerSpacing="spacious"
        contentSpacing="spacious"
        variant="outlined"
      >
        <p>Premium feel with generous whitespace</p>
      </CollapsibleLayout>

      {/* Mixed spacing */}
      <CollapsibleLayout
        title="Mixed Spacing"
        subtitle="Compact header, spacious content"
        headerSpacing="compact"
        contentSpacing="spacious"
        variant="outlined"
      >
        <p>Customize header and content spacing independently</p>
      </CollapsibleLayout>
    </div>
  );
}

Advanced Content Features

Header Customization

import { Settings, Star, MoreVert } from '@mui/icons-material';

function HeaderCustomization() {
  return (
    <div>
      {/* With lead icon and header actions */}
      <CollapsibleLayout
        title="User Profile Settings"
        subtitle="Manage your account preferences"
        leadIcon={<Settings color="primary" />}
        headerActions={
          <div style={{ display: 'flex', gap: '8px', alignItems: 'center' }}>
            <span style={{ 
              fontSize: '12px', 
              backgroundColor: '#4caf50', 
              color: 'white', 
              padding: '2px 8px', 
              borderRadius: '12px' 
            }}>
              Pro
            </span>
            <button>Edit</button>
            <MoreVert />
          </div>
        }
      >
        <div>
          <input type="text" placeholder="Display Name" />
          <input type="email" placeholder="Email Address" />
          <textarea placeholder="Bio"></textarea>
        </div>
      </CollapsibleLayout>
    </div>
  );
}

Collapsed Preview Content

function CollapsedPreviewExample() {
  return (
    <CollapsibleLayout
      title="Article Preview"
      subtitle="Click to read the full article"
      defaultCollapsed={true}
      variant="outlined"
      collapsedView={
        <div style={{ 
          padding: '12px', 
          backgroundColor: '#f5f5f5', 
          borderRadius: '4px',
          color: '#666'
        }}>
          📖 This article covers advanced React patterns and best practices 
          for building scalable applications. Click to expand and read more...
        </div>
      }
    >
      <div>
        <h3>Advanced React Patterns</h3>
        <p>
          React has evolved significantly over the years, and with it, the patterns 
          and practices that help developers build maintainable, scalable applications. 
          In this comprehensive guide, we'll explore some of the most powerful advanced patterns.
        </p>
        <h4>1. Compound Components</h4>
        <p>
          Compound components provide a flexible and intuitive API for components that 
          need to work together...
        </p>
        <button>Read More</button>
      </div>
    </CollapsibleLayout>
  );
}

Footer Content

function FooterContentExample() {
  return (
    <CollapsibleLayout
      title="Project Status"
      subtitle="Development progress and information"
      defaultCollapsed={false}
      footerView={
        <div style={{ 
          display: 'flex', 
          justifyContent: 'space-between', 
          alignItems: 'center',
          paddingTop: '8px',
          borderTop: '1px solid #eee',
          marginTop: '16px'
        }}>
          <small style={{ color: '#666' }}>
            Last updated: 2 hours ago
          </small>
          <button>View Details</button>
        </div>
      }
    >
      <div>
        <div style={{ marginBottom: '16px' }}>
          <strong>Development: Complete ✅</strong>
        </div>
        <div style={{ marginBottom: '16px' }}>
          <strong>Testing: In Progress ⚠️</strong>
        </div>
        <div style={{ 
          height: '8px', 
          backgroundColor: '#e0e0e0', 
          borderRadius: '4px',
          overflow: 'hidden'
        }}>
          <div style={{ 
            height: '100%', 
            width: '75%', 
            backgroundColor: '#4caf50',
            borderRadius: '4px'
          }}></div>
        </div>
        <small style={{ color: '#666' }}>Project is 75% complete</small>
      </div>
    </CollapsibleLayout>
  );
}

Interaction Patterns

Trigger Areas

Control how users can expand/collapse the layout:

function TriggerAreaExamples() {
  return (
    <div>
      {/* Header trigger - click anywhere on header */}
      <CollapsibleLayout
        title="Header Trigger"
        subtitle="Click anywhere on the header"
        triggerArea="header"
        variant="outlined"
      >
        <p>Header area is clickable, no separate button</p>
      </CollapsibleLayout>

      {/* Button trigger - only the button works */}
      <CollapsibleLayout
        title="Button Trigger"
        subtitle="Only the button toggles content"
        triggerArea="button"
        variant="outlined"
      >
        <p>Only the toggle button expands/collapses this</p>
      </CollapsibleLayout>

      {/* Both triggers - header or button */}
      <CollapsibleLayout
        title="Both Triggers"
        subtitle="Header or button can toggle"
        triggerArea="both"
        variant="outlined"
      >
        <p>You can click the header OR use the toggle button</p>
      </CollapsibleLayout>
    </div>
  );
}

Custom Icons

import { ArrowDropDown, ArrowDropUp, ExpandMore, ExpandLess } from '@mui/icons-material';

function CustomIconExamples() {
  return (
    <div>
      {/* Material-UI icons */}
      <CollapsibleLayout
        title="Custom Material Icons"
        collapsedIcon={<ArrowDropDown />}
        expandedIcon={<ArrowDropUp />}
        defaultCollapsed={false}
      >
        <p>Using ArrowDropDown and ArrowDropUp icons</p>
      </CollapsibleLayout>

      {/* Emoji icons */}
      <CollapsibleLayout
        title="Emoji Icons"
        collapsedIcon="▶️"
        expandedIcon="🔽"
        defaultCollapsed={false}
      >
        <p>Using emoji as toggle icons</p>
      </CollapsibleLayout>

      {/* HTML string icons */}
      <CollapsibleLayout
        title="HTML Icons"
        collapsedIcon='<span style="color: #4caf50;">+</span>'
        expandedIcon='<span style="color: #f44336;">−</span>'
        defaultCollapsed={false}
      >
        <p>Using HTML strings for custom styled icons</p>
      </CollapsibleLayout>
    </div>
  );
}

State Persistence

localStorage Integration

function PersistentStateExample() {
  return (
    <div>
      <p style={{ 
        backgroundColor: '#e3f2fd', 
        padding: '12px', 
        borderRadius: '4px',
        marginBottom: '16px'
      }}>
        💡 Try collapsing the sections below and refreshing the page - 
        the states will be remembered!
      </p>

      <CollapsibleLayout
        title="Persistent Settings"
        subtitle="This state is saved automatically"
        defaultCollapsed={false}
        persistState={true}
        storageKey="user-settings-section"
        variant="elevated"
      >
        <div>
          <label>
            <input type="checkbox" /> Enable notifications
          </label>
          <br />
          <label>
            <input type="checkbox" /> Auto-save changes
          </label>
          <br />
          <button>Save Settings</button>
        </div>
      </CollapsibleLayout>

      <CollapsibleLayout
        title="Persistent Preferences"
        subtitle="Another independently persisted section"
        defaultCollapsed={true}
        persistState={true}
        storageKey="user-preferences-section"
        variant="elevated"
      >
        <div>
          <select>
            <option>Light Theme</option>
            <option>Dark Theme</option>
            <option>Auto</option>
          </select>
          <br />
          <input type="range" min="0" max="100" defaultValue="50" />
          <br />
          <button>Apply Preferences</button>
        </div>
      </CollapsibleLayout>
    </div>
  );
}

Data Binding Support

CMS Integration

import { QwickApp, CollapsibleLayout } from '@qwickapps/react-framework';
import { JsonDataProvider } from '@qwickapps/schema';

// Sample CMS data structure
const cmsData = {
  'collapsible-sections': {
    'faq-section': {
      title: 'Frequently Asked Questions',
      subtitle: 'Common questions and answers',
      defaultCollapsed: false,
      variant: 'outlined',
      animationStyle: 'fade',
      persistState: true,
      storageKey: 'faq-section-state'
    },
    'help-section': {
      title: 'Help & Support',
      subtitle: 'Get assistance and documentation',
      defaultCollapsed: true,
      variant: 'elevated',
      leadIcon: '❓',
      collapsedView: '<p style="color: #666;"><em>Click to expand help resources...</em></p>'
    }
  }
};

function DataBindingExample() {
  const dataProvider = new JsonDataProvider({ data: cmsData });

  return (
    <QwickApp
      appId="collapsible-demo"
      appName="Data Binding Demo"
      dataSource={{ dataProvider }}
    >
      {/* FAQ section driven by CMS data */}
      <CollapsibleLayout dataSource="collapsible-sections.faq-section">
        <div>
          <h3>How do I install the framework?</h3>
          <p>Run `npm install @qwickapps/react-framework` in your project.</p>
          
          <h3>Is TypeScript supported?</h3>
          <p>Yes, full TypeScript support is included with complete type definitions.</p>
          
          <h3>Can I customize the styling?</h3>
          <p>Absolutely! Use the sx prop, CSS custom properties, or extend components.</p>
        </div>
      </CollapsibleLayout>

      {/* Help section driven by CMS data */}
      <CollapsibleLayout dataSource="collapsible-sections.help-section">
        <div>
          <ul>
            <li><a href="/docs">📖 Documentation</a></li>
            <li><a href="/examples">💡 Examples</a></li>
            <li><a href="/support">🎧 Support</a></li>
            <li><a href="/community">👥 Community</a></li>
          </ul>
        </div>
      </CollapsibleLayout>
    </QwickApp>
  );
}

Props API Reference