@qwickapps/react-framework 1.3.0

package/src/stories/LayoutBlocks.stories.tsx

@@ -0,0 +1,382 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { 
+  HeroBlock, 
+  Content, 
+  FeatureGrid, 
+  Section 
+} from '../components/blocks';
+import { 
+  GridLayout, 
+  GridCell
+} from '../components/layout';
+import { QwickApp } from '../components/QwickApp';
+import { Button } from '../components/buttons/Button';
+
+const meta: Meta = {
+  title: 'Layout/LayoutBlocks',
+  decorators: [
+    (Story) => (
+      <QwickApp appName="Layout Demo">
+        <Story />
+      </QwickApp>
+    ),
+  ],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component: `Comprehensive collection of layout components for building responsive, professional content layouts with minimal effort.
+
+**Key Features:**
+- **HeroBlock**: Full-width hero sections with background images, gradients, and call-to-action buttons
+- **GridLayout**: Responsive multi-column layouts (1-5 columns) with automatic mobile adaptation
+- **GridCell**: Flexible column component with background colors, spacing, and elevation options
+- **Content**: Structured content containers with titles, variants, and action buttons
+- **FeatureGrid**: Grid layouts for showcasing features with icons, titles, and descriptions
+- **Section**: Page-level containers with theming, spacing, and max-width controls
+- **Responsive Design**: All components automatically adapt to mobile, tablet, and desktop
+- **Theme Integration**: Full support for theme colors, spacing, and typography
+
+**Perfect for:**
+- Landing pages and marketing websites
+- Product feature showcases and comparisons
+- Documentation and help pages
+- Dashboard layouts and admin panels
+- Blog posts and article layouts
+- Portfolio and showcase websites
+- Any application requiring structured content presentation`,
+      },
+    },
+  },
+};
+
+export default meta;
+
+// Hero Block Stories
+export const HeroBlocks: StoryObj = {
+  render: () => (
+    <div>
+      <HeroBlock
+        title="Welcome to QwickApps React Framework"
+        subtitle="Build beautiful, responsive React applications with ease"
+        backgroundGradient="linear-gradient(135deg, #667eea 0%, #764ba2 100%)"
+        height="medium"
+        actions={[
+          {
+            label: 'Get Started',
+            variant: 'primary',
+            onClick: () => { alert('Get Started clicked'); }
+          },
+          {
+            label: 'Learn More',
+            variant: 'outlined',
+            onClick: () => { alert('Learn More clicked'); }
+          }
+        ]}
+      />
+      
+      <Section spacing="spacious">
+        <HeroBlock
+          title="Small Hero with Image"
+          subtitle="This hero uses a background image with overlay"
+          backgroundImage="https://images.unsplash.com/photo-1558618666-fcd25c85cd64?ixlib=rb-4.0.3&auto=format&fit=crop&w=1200&q=80"
+          height="small"
+          overlayOpacity={0.7}
+          textAlign="left"
+        />
+      </Section>
+    </div>
+  ),
+};
+
+// GridCell Layout Stories
+export const ColumnLayouts: StoryObj = {
+  render: () => (
+    <div>
+      <Section spacing="spacious">
+        <Content title="Two GridCell Layout" centered>
+          <GridLayout columns={2} spacing="large">
+            <GridCell background="background.paper">
+              <h3>Left GridCell</h3>
+              <p>This is the left column content with automatic responsive behavior.</p>
+            </GridCell>
+            <GridCell background="grey.100">
+              <h3>Right GridCell</h3>
+              <p>This is the right column content that will stack below on mobile.</p>
+            </GridCell>
+          </GridLayout>
+        </Content>
+      </Section>
+
+      <Section background="grey.50">
+        <Content title="Three GridCell Layout" centered>
+          <GridLayout columns={3} spacing="medium" equalHeight>
+            <GridCell background="background.paper">
+              <h4>Feature One</h4>
+              <p>Equal height columns ensure consistent layout.</p>
+            </GridCell>
+            <GridCell background="background.paper">
+              <h4>Feature Two</h4>
+              <p>This column has more content to demonstrate the equal height functionality working properly.</p>
+            </GridCell>
+            <GridCell background="background.paper">
+              <h4>Feature Three</h4>
+              <p>Short content.</p>
+            </GridCell>
+          </GridLayout>
+        </Content>
+      </Section>
+
+      <Section spacing="spacious">
+        <Content title="Four & Five GridCell Layouts" centered>
+          <GridLayout columns={4} spacing="small" sx={{ mb: 3 }}>
+            {[1, 2, 3, 4].map((i) => (
+              <GridCell key={i} background="primary.main" sx={{ textAlign: 'center' }}>
+                <strong>Col {i}</strong>
+              </GridCell>
+            ))}
+          </GridLayout>
+          
+          <GridLayout columns={5} spacing="small">
+            {[1, 2, 3, 4, 5].map((i) => (
+              <GridCell key={i} background="grey.200" sx={{ textAlign: 'center' }}>
+                <strong>{i}</strong>
+              </GridCell>
+            ))}
+          </GridLayout>
+        </Content>
+      </Section>
+    </div>
+  ),
+};
+
+// Content Block Stories
+export const Contents: StoryObj = {
+  render: () => (
+    <div>
+      <Section spacing="spacious">
+        <Content 
+          title="Default Content Block" 
+          centered
+          maxWidth="md"
+        >
+          <p>This is a default content block with automatic responsive behavior and theme-aware styling.</p>
+        </Content>
+      </Section>
+
+      <Section background="default">
+        <Content 
+          title="Elevated Content Block" 
+          variant="elevated"
+          spacing="spacious"
+          centered
+          maxWidth="md"
+        >
+          <p>This elevated content block has a subtle shadow and stands out from the background.</p>
+        </Content>
+      </Section>
+
+      <Section spacing="spacious">
+        <GridLayout columns={2} spacing="large">
+          <GridCell>
+            <Content 
+              title="Outlined Block" 
+              variant="outlined"
+              spacing="spacious"
+            >
+              <p>This content block has a border instead of a shadow.</p>
+            </Content>
+          </GridCell>
+          <GridCell>
+            <Content 
+              title="Filled Block" 
+              variant="filled"
+              spacing="spacious"
+            >
+              <p>This content block has a filled background color.</p>
+            </Content>
+          </GridCell>
+        </GridLayout>
+      </Section>
+    </div>
+  ),
+};
+
+// Feature Grid Stories
+export const FeatureGrids: StoryObj = {
+  render: () => (
+    <div>
+      <Section spacing="spacious">
+        <Content title="Feature Grid" centered maxWidth="lg">
+          <FeatureGrid
+            columns={3}
+            gap="large"
+            features={[
+              {
+                id: 'responsive',
+                icon: <span style={{ fontSize: '2rem' }}>📱</span>,
+                title: 'Responsive Design',
+                description: 'All components automatically adapt to different screen sizes for optimal user experience.',
+                action: <Button label="Learn More" buttonSize="small" onClick={() => { alert('Learn More clicked'); }} />
+              },
+              {
+                id: 'themes',
+                icon: <span style={{ fontSize: '2rem' }}>🎨</span>,
+                title: 'Theme Support',
+                description: 'Built-in light/dark theme support with customizable color palettes.',
+                action: <Button label="Explore" buttonSize="small" onClick={() => { alert('Explore clicked'); }} />
+              },
+              {
+                id: 'accessible',
+                icon: <span style={{ fontSize: '2rem' }}>♿</span>,
+                title: 'Accessibility First',
+                description: 'All components follow WCAG guidelines and include proper ARIA labels.',
+                action: <Button label="Details" buttonSize="small" onClick={() => { alert('Details clicked'); }} />
+              },
+              {
+                id: 'typescript',
+                icon: <span style={{ fontSize: '2rem' }}>🔷</span>,
+                title: 'TypeScript Ready',
+                description: 'Full TypeScript support with comprehensive type definitions.',
+                action: <Button label="Documentation" buttonSize="small" onClick={() => { alert('Documentation clicked'); }} />
+              },
+              {
+                id: 'performance',
+                icon: <span style={{ fontSize: '2rem' }}>⚡</span>,
+                title: 'High Performance',
+                description: 'Optimized for speed with minimal bundle size and efficient rendering.',
+                action: <Button label="Benchmarks" buttonSize="small" onClick={() => { alert('Benchmarks clicked'); }} />
+              },
+              {
+                id: 'customizable',
+                icon: <span style={{ fontSize: '2rem' }}>🛠️</span>,
+                title: 'Highly Customizable',
+                description: 'Easy to customize and extend with your own design system.',
+                action: <Button label="Customize" buttonSize="small" onClick={() => { alert('Customize clicked'); }} />
+              },
+            ]}
+          />
+        </Content>
+      </Section>
+    </div>
+  ),
+};
+
+// Complete Layout Example
+export const CompleteLayout: StoryObj = {
+  render: () => (
+    <div>
+      {/* Hero Section */}
+      <HeroBlock
+        title="QwickApps React Framework"
+        subtitle="The complete React framework for building modern applications"
+        backgroundGradient="linear-gradient(135deg, #667eea 0%, #764ba2 100%)"
+        height="large"
+        actions={[
+          {
+            label: 'Get Started',
+            variant: 'primary',
+            size: 'large',
+            onClick: () => { alert('Get Started clicked'); }
+          },
+          {
+            label: 'View Demo',
+            variant: 'outlined',
+            size: 'large',
+            onClick: () => { alert('View Demo clicked'); }
+          }
+        ]}
+      />
+
+      {/* Features Section */}
+      <Section background="alternate">
+        <Content title="Why Choose QwickApps?" centered maxWidth="lg">
+          <p style={{ fontSize: '1.2rem', textAlign: 'center', marginBottom: '3rem', opacity: 0.8 }}>
+            Everything you need to build beautiful, responsive applications
+          </p>
+          <FeatureGrid
+            columns={3}
+            gap="large"
+            features={[
+              {
+                id: 'components',
+                icon: <span style={{ fontSize: '3rem' }}>🧩</span>,
+                title: 'Rich Components',
+                description: 'Comprehensive set of pre-built, customizable components for rapid development.',
+              },
+              {
+                id: 'layouts',
+                icon: <span style={{ fontSize: '3rem' }}>📐</span>,
+                title: 'Flexible Layouts',
+                description: 'Powerful layout blocks that adapt to any design and screen size automatically.',
+              },
+              {
+                id: 'navigation',
+                icon: <span style={{ fontSize: '3rem' }}>🧭</span>,
+                title: 'Smart Navigation',
+                description: 'Responsive navigation that transforms based on device: bottom nav, rail, or top nav.',
+              },
+            ]}
+          />
+        </Content>
+      </Section>
+
+      {/* Content Sections */}
+      <Section spacing="spacious">
+        <GridLayout columns={2} spacing="large">
+          <GridCell>
+            <Content title="Easy to Use" variant="elevated" spacing="spacious">
+              <p>QwickApps React Framework is designed for developers who want to build great applications without spending time on boilerplate.</p>
+              <ul>
+                <li>Simple API design</li>
+                <li>Comprehensive documentation</li>
+                <li>TypeScript support</li>
+                <li>Storybook examples</li>
+              </ul>
+            </Content>
+          </GridCell>
+          <GridCell>
+            <Content title="Production Ready" variant="elevated" spacing="spacious">
+              <p>Built with best practices and tested in real-world applications to ensure reliability and performance.</p>
+              <ul>
+                <li>Accessibility compliant</li>
+                <li>Performance optimized</li>
+                <li>Theme system</li>
+                <li>Mobile-first design</li>
+              </ul>
+            </Content>
+          </GridCell>
+        </GridLayout>
+      </Section>
+
+      {/* Call to Action */}
+      <Section background="primary">
+        <Content 
+          centered 
+          maxWidth="md" 
+          actions={[
+            {
+              label: 'Start Building',
+              variant: 'secondary',
+              size: 'large',
+              onClick: () => { alert('Start Building clicked'); }
+            },
+            {
+              label: 'Documentation',
+              variant: 'outlined',
+              size: 'large',
+              onClick: () => console.log('Documentation clicked')
+            }
+          ]}
+        >
+          <h2 style={{ fontSize: '2.5rem', marginBottom: '1rem' }}>
+            Ready to Get Started?
+          </h2>
+          <p style={{ fontSize: '1.2rem', opacity: 0.9, marginBottom: '2rem' }}>
+            Join thousands of developers building with QwickApps React Framework
+          </p>
+        </Content>
+      </Section>
+    </div>
+  ),
+};

package/src/stories/LayoutSystem.stories.tsx

@@ -0,0 +1,253 @@
+/**
+ * Layout System - Complete guide to QwickApps layout components
+ */
+
+import type { Meta, StoryObj } from '@storybook/react';
+import { Box, Typography, Paper, Chip } from '@mui/material';
+import { GridLayout } from '../components/layout/GridLayout';
+import { 
+  HeroBlock, 
+  Content, 
+  Section 
+} from '../components/blocks';
+import { QwickApp } from '../components/QwickApp';
+
+const meta: Meta = {
+  title: 'Layout/Layout System',
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component: `Complete layout system for building responsive, professional interfaces with minimal code.
+
+**Key Features:**
+- **GridLayout**: Flexible CSS Grid-based layout with automatic responsive behavior
+- **GridCell**: Simple wrapper for custom content with base props support
+- **LayoutBlocks**: Pre-built content blocks (Hero, Content, Feature Grid, Section)
+- **Base Props**: Standardized props for all layout components (spacing, dimensions, grid behavior)
+- **Responsive Design**: Automatic mobile-first responsive behavior
+- **T-shirt Sizing**: Intuitive sizing system (tiny, small, medium, large, huge)
+
+**Perfect For:**
+- Landing pages and marketing websites
+- Dashboard and admin panel layouts
+- Content-heavy applications and blogs
+- E-commerce product showcases
+- Documentation and help systems
+- Any application requiring structured, responsive layouts`,
+      },
+    },
+  },
+};
+
+export default meta;
+
+export const LayoutSystemOverview: StoryObj = {
+  render: () => (
+    <QwickApp appName="Layout System Demo">
+      <Section sectionBackground="background.default" padding="comfortable">
+        <Typography variant="h3" gutterBottom>
+          QwickApps Layout System
+        </Typography>
+        
+        <Typography variant="h5" color="text.secondary" paragraph>
+          Build responsive layouts with our comprehensive layout component system
+        </Typography>
+
+        <GridLayout columns={2} spacing="large" margin="large">
+          <Content
+            title="GridLayout"
+            variant="elevated"
+            blockSpacing="comfortable"
+          >
+            <Typography paragraph>
+              CSS Grid-based layout component that automatically wraps child components 
+              with grid props in Material-UI Grid items.
+            </Typography>
+            <Box sx={{ display: 'flex', gap: 1, flexWrap: 'wrap' }}>
+              <Chip label="Responsive" size="small" />
+              <Chip label="Auto-wrapping" size="small" />
+              <Chip label="Flexible columns" size="small" />
+            </Box>
+          </Content>
+
+          <Content
+            title="LayoutBlocks"
+            variant="elevated"
+            blockSpacing="comfortable"
+          >
+            <Typography paragraph>
+              Pre-built content blocks including Hero sections, Content blocks, 
+              Feature grids, and Section containers for rapid development.
+            </Typography>
+            <Box sx={{ display: 'flex', gap: 1, flexWrap: 'wrap' }}>
+              <Chip label="Pre-styled" size="small" />
+              <Chip label="Theme-aware" size="small" />
+              <Chip label="Content-ready" size="small" />
+            </Box>
+          </Content>
+
+          <Content
+            title="Base Props System"
+            variant="elevated"
+            blockSpacing="comfortable"
+            span={12}
+          >
+            <Typography paragraph>
+              All layout components support standardized base props for consistent 
+              styling, spacing, and grid behavior across your application.
+            </Typography>
+            <GridLayout columns={4} spacing="small">
+              <Paper sx={{ p: 1, textAlign: 'center', background: '#e3f2fd' }}>
+                <Typography variant="caption" display="block">Grid Props</Typography>
+                <Typography variant="body2">span, xs, sm, md, lg, xl</Typography>
+              </Paper>
+              <Paper sx={{ p: 1, textAlign: 'center', background: '#e8f5e8' }}>
+                <Typography variant="caption" display="block">Dimensions</Typography>
+                <Typography variant="body2">width, height, min/max</Typography>
+              </Paper>
+              <Paper sx={{ p: 1, textAlign: 'center', background: '#fff3e0' }}>
+                <Typography variant="caption" display="block">Spacing</Typography>
+                <Typography variant="body2">padding, margin</Typography>
+              </Paper>
+              <Paper sx={{ p: 1, textAlign: 'center', background: '#fce4ec' }}>
+                <Typography variant="caption" display="block">Styling</Typography>
+                <Typography variant="body2">background, className, sx</Typography>
+              </Paper>
+            </GridLayout>
+          </Content>
+        </GridLayout>
+      </Section>
+
+      <Section sectionBackground="grey.50" padding="comfortable">
+        <Typography variant="h4" gutterBottom>
+          T-shirt Sizing System
+        </Typography>
+        
+        <Typography variant="body1" paragraph>
+          All components support intuitive t-shirt sizing for dimensions and spacing:
+        </Typography>
+
+        <GridLayout columns={5} spacing="medium">
+          <Paper sx={{ p: 2, textAlign: 'center', background: 'primary.light' }}>
+            <Typography variant="h6" color="primary.contrastText">Tiny</Typography>
+            <Typography variant="caption" color="primary.contrastText">4px / 0.25rem</Typography>
+          </Paper>
+          <Paper sx={{ p: 2, textAlign: 'center', background: 'secondary.light' }}>
+            <Typography variant="h6" color="secondary.contrastText">Small</Typography>
+            <Typography variant="caption" color="secondary.contrastText">8px / 0.5rem</Typography>
+          </Paper>
+          <Paper sx={{ p: 2, textAlign: 'center', background: 'success.light' }}>
+            <Typography variant="h6" color="success.contrastText">Medium</Typography>
+            <Typography variant="caption" color="success.contrastText">16px / 1rem</Typography>
+          </Paper>
+          <Paper sx={{ p: 2, textAlign: 'center', background: 'warning.light' }}>
+            <Typography variant="h6" color="warning.contrastText">Large</Typography>
+            <Typography variant="caption" color="warning.contrastText">24px / 1.5rem</Typography>
+          </Paper>
+          <Paper sx={{ p: 2, textAlign: 'center', background: 'error.light' }}>
+            <Typography variant="h6" color="error.contrastText">Huge</Typography>
+            <Typography variant="caption" color="error.contrastText">32px / 2rem</Typography>
+          </Paper>
+        </GridLayout>
+      </Section>
+
+      <HeroBlock
+        title="Start Building Beautiful Layouts"
+        subtitle="Use GridLayout and LayoutBlocks to create responsive, professional interfaces"
+        actions={[
+          { label: "View GridLayout Stories", variant: "primary" },
+          { label: "View LayoutBlocks Stories", variant: "outlined" }
+        ]}
+        backgroundColor="primary"
+        blockHeight="small"
+      />
+    </QwickApp>
+  ),
+};
+
+export const GridLayoutDemo: StoryObj = {
+  render: () => (
+    <QwickApp appName="GridLayout Demo">
+      <Section padding="comfortable">
+        <Typography variant="h4" gutterBottom>
+          GridLayout Examples
+        </Typography>
+
+        <Content title="Equal Column Distribution" blockSpacing="comfortable" margin="large">
+          <Typography paragraph>
+            Use the <code>columns</code> prop to automatically distribute children into equal-width columns:
+          </Typography>
+          <GridLayout columns={3} spacing="medium">
+            <Paper sx={{ p: 2, textAlign: 'center', background: '#ffebee' }}>
+              <Typography>Column 1</Typography>
+            </Paper>
+            <Paper sx={{ p: 2, textAlign: 'center', background: '#e8f5e8' }}>
+              <Typography>Column 2</Typography>
+            </Paper>
+            <Paper sx={{ p: 2, textAlign: 'center', background: '#e3f2fd' }}>
+              <Typography>Column 3</Typography>
+            </Paper>
+          </GridLayout>
+        </Content>
+
+        <Content title="Custom Grid Spans" blockSpacing="comfortable" margin="large">
+          <Typography paragraph>
+            Use <code>span</code> props on children for custom column widths:
+          </Typography>
+          <GridLayout spacing="medium">
+            <Paper sx={{ p: 2, textAlign: 'center', background: '#f3e5f5' }} data-grid-span={8}>
+              <Typography>Main Content (8 columns)</Typography>
+            </Paper>
+            <Paper sx={{ p: 2, textAlign: 'center', background: '#e0f2f1' }} data-grid-span={4}>
+              <Typography>Sidebar (4 columns)</Typography>
+            </Paper>
+          </GridLayout>
+        </Content>
+
+        <Content title="Responsive Behavior" blockSpacing="comfortable" margin="large">
+          <Typography paragraph>
+            Use breakpoint props for responsive layouts:
+          </Typography>
+          <GridLayout spacing="medium">
+            <Paper 
+              sx={{ p: 2, textAlign: 'center', background: '#fff3e0' }}
+              data-grid-xs={12}
+              data-grid-sm={6}
+              data-grid-md={4}
+            >
+              <Typography variant="body2">
+                Mobile: Full width<br/>
+                Tablet: Half width<br/>
+                Desktop: One third
+              </Typography>
+            </Paper>
+            <Paper 
+              sx={{ p: 2, textAlign: 'center', background: '#fce4ec' }}
+              data-grid-xs={12}
+              data-grid-sm={6}
+              data-grid-md={4}
+            >
+              <Typography variant="body2">
+                Responsive<br/>
+                Column 2
+              </Typography>
+            </Paper>
+            <Paper 
+              sx={{ p: 2, textAlign: 'center', background: '#e8eaf6' }}
+              data-grid-xs={12}
+              data-grid-sm={12}
+              data-grid-md={4}
+            >
+              <Typography variant="body2">
+                Mobile: Full width<br/>
+                Tablet: Full width<br/>
+                Desktop: One third
+              </Typography>
+            </Paper>
+          </GridLayout>
+        </Content>
+      </Section>
+    </QwickApp>
+  ),
+};