@qwickapps/react-framework 1.3.0

package/src/stories/HeroBlock.stories.tsx

@@ -0,0 +1,442 @@
+/**
+ * HeroBlock Component Stories - Hero sections with data binding support
+ * 
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import { Box, Typography } from '@mui/material';
+import { JsonDataProvider } from '@qwickapps/schema';
+import type { Meta, StoryObj } from '@storybook/react';
+import QwickApp from '../components/QwickApp';
+import { Code } from '../components/blocks';
+import HeroBlock from '../components/blocks/HeroBlock';
+import { DataProvider } from '../contexts/DataContext';
+
+// Sample CMS data for data binding stories
+const sampleCmsData = {
+  'heroes': {
+    'home': {
+      title: 'Build Apps 10x Faster with QwickApps',
+      subtitle: 'The most developer-friendly React framework that turns complex UI development into a joy. Build production-ready applications in hours, not weeks.',
+      backgroundGradient: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
+      actions: [
+        { label: 'Get Started Free', variant: 'primary', buttonSize: 'large' },
+        { label: 'Watch Demo', variant: 'outlined', buttonSize: 'large', icon: '▶️' }
+      ],
+      textAlign: 'center',
+      blockHeight: 'large',
+      overlayOpacity: 0.6
+    },
+    'product-launch': {
+      title: '🚀 Revolutionary New Framework',
+      subtitle: 'Skip months of boilerplate setup. Focus on what makes your application unique.',
+      backgroundImage: 'https://images.unsplash.com/photo-1558618666-fcd25c85cd64?ixlib=rb-4.0.3&auto=format&fit=crop&w=1200&q=80',
+      actions: [
+        { label: 'Launch Now', variant: 'primary', buttonSize: 'large' },
+        { label: 'View Features', variant: 'text', buttonSize: 'large' }
+      ],
+      textAlign: 'center',
+      blockHeight: 'viewport',
+      overlayOpacity: 0.7
+    },
+    'about': {
+      title: 'Empowering Developers Worldwide',
+      subtitle: 'Our mission is to make web development accessible, enjoyable, and productive for everyone.',
+      backgroundColor: 'primary',
+      actions: [
+        { label: 'Our Story', variant: 'secondary', buttonSize: 'medium' },
+        { label: 'Join Team', variant: 'outlined', buttonSize: 'medium' }
+      ],
+      textAlign: 'left',
+      blockHeight: 'medium'
+    },
+    'minimal': {
+      title: 'Simple. Powerful. Elegant.',
+      subtitle: 'Everything you need, nothing you don\'t.',
+      backgroundColor: 'surface',
+      blockHeight: 'small',
+      textAlign: 'center'
+    }
+  }
+};
+
+const dataProvider = new JsonDataProvider({ data: sampleCmsData });
+
+const meta = {
+  title: 'Blocks/HeroBlock',
+  component: HeroBlock,
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component: `HeroBlock is a powerful full-width hero section component that supports both traditional props and data binding through dataSource.
+
+**Key Features:**
+- **Flexible Backgrounds**: Support for images, gradients, and theme colors
+- **Responsive Typography**: Automatically scales from mobile to desktop
+- **Action Buttons**: Built-in support for multiple call-to-action buttons
+- **Height Variants**: Small, medium, large, and full viewport options
+- **Text Alignment**: Left, center, or right alignment options
+- **Data Binding**: Full CMS integration through dataSource prop
+- **Overlay Control**: Customizable overlay opacity for background images
+
+**Perfect For:**
+- Landing page heroes and primary messaging
+- Product launch announcements
+- Marketing campaigns and promotions  
+- About pages and company messaging
+- Feature highlights and value propositions`,
+      },
+    },
+  },
+  tags: ['autodocs'],
+} satisfies Meta<typeof HeroBlock>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// Traditional Usage Examples
+export const BasicHero: Story = {
+  render: () => (
+    <QwickApp appId="heroblock-basic" appName='Basic HeroBlock'>
+      <HeroBlock
+        title="Welcome to Our Platform"
+        subtitle="Build amazing applications with our comprehensive toolkit"
+        backgroundColor="primary"
+        textAlign="center"
+        blockHeight="medium"
+        actions={[
+          { label: 'Get Started', variant: 'primary', buttonSize: 'large' },
+          { label: 'Learn More', variant: 'outlined', buttonSize: 'large' }
+        ]}
+      />
+    </QwickApp>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Basic HeroBlock with traditional props - title, subtitle, actions, and theme background.',
+      },
+    },
+  },
+};
+
+export const BackgroundVariants: Story = {
+  render: () => (
+    <QwickApp appId="heroblock-backgrounds" appName='HeroBlock Backgrounds'>
+      <Box sx={{ '& > *:not(:last-child)': { mb: 2 } }}>
+        
+        <HeroBlock
+          title="Gradient Background Hero"
+          subtitle="Beautiful gradients create visual impact"
+          backgroundGradient="linear-gradient(135deg, #667eea 0%, #764ba2 100%)"
+          blockHeight="medium"
+          actions={[{ label: 'Explore', variant: 'primary', buttonSize: 'large' }]}
+        />
+        
+        <HeroBlock
+          title="Image Background Hero"
+          subtitle="High-quality images with customizable overlay"
+          backgroundImage="https://images.unsplash.com/photo-1558618666-fcd25c85cd64?ixlib=rb-4.0.3&auto=format&fit=crop&w=1200&q=80"
+          overlayOpacity={0.6}
+          blockHeight="medium"
+          actions={[{ label: 'Discover', variant: 'primary', buttonSize: 'large' }]}
+        />
+        
+        <HeroBlock
+          title="Theme Color Background"
+          subtitle="Consistent with your application theme"
+          backgroundColor="secondary"
+          blockHeight="medium"
+          actions={[{ label: 'Continue', variant: 'primary', buttonSize: 'large' }]}
+        />
+        
+      </Box>
+    </QwickApp>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Different background options: gradients, images with overlay, and theme colors.',
+      },
+    },
+  },
+};
+
+export const HeightVariants: Story = {
+  render: () => (
+    <QwickApp appId="heroblock-heights" appName='HeroBlock Heights'>
+      <Box sx={{ '& > *:not(:last-child)': { mb: 1 } }}>
+        
+        <HeroBlock
+          title="Small Height Hero"
+          subtitle="Compact hero for minimal messaging"
+          backgroundColor="primary"
+          blockHeight="small"
+          textAlign="center"
+        />
+        
+        <HeroBlock
+          title="Medium Height Hero (Default)"
+          subtitle="Balanced height for most use cases"
+          backgroundColor="secondary"
+          blockHeight="medium"
+          textAlign="center"
+        />
+        
+        <HeroBlock
+          title="Large Height Hero"
+          subtitle="Expansive hero for maximum impact"
+          backgroundGradient="linear-gradient(45deg, #2196F3, #21CBF3)"
+          blockHeight="large"
+          textAlign="center"
+        />
+        
+        <Box sx={{ height: '50vh', overflow: 'hidden' }}>
+          <HeroBlock
+            title="Viewport Height Hero"
+            subtitle="Full-screen dramatic effect"
+            backgroundGradient="linear-gradient(135deg, #667eea 0%, #764ba2 100%)"
+            blockHeight="viewport"
+            textAlign="center"
+          />
+        </Box>
+        
+      </Box>
+    </QwickApp>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Available height options: small (300px), medium (400px), large (600px), and viewport (100vh).',
+      },
+    },
+  },
+};
+
+export const TextAlignment: Story = {
+  render: () => (
+    <QwickApp appId="heroblock-alignment" appName='HeroBlock Text Alignment'>
+      <Box sx={{ '& > *:not(:last-child)': { mb: 2 } }}>
+        
+        <HeroBlock
+          title="Left Aligned Hero"
+          subtitle="Content-heavy heroes work well with left alignment"
+          backgroundColor="surface"
+          textAlign="left"
+          blockHeight="medium"
+          actions={[{ label: 'Read More', variant: 'primary' }]}
+        />
+        
+        <HeroBlock
+          title="Center Aligned Hero"
+          subtitle="Traditional center alignment for maximum impact"
+          backgroundGradient="linear-gradient(45deg, #2196F3, #21CBF3)"
+          textAlign="center"
+          blockHeight="medium"
+          actions={[{ label: 'Get Started', variant: 'primary' }]}
+        />
+        
+        <HeroBlock
+          title="Right Aligned Hero"
+          subtitle="Unique visual balance with right alignment"
+          backgroundColor="secondary"
+          textAlign="right"
+          blockHeight="medium"
+          actions={[{ label: 'Learn More', variant: 'primary' }]}
+        />
+        
+      </Box>
+    </QwickApp>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Text alignment options: left (content-heavy), center (traditional), right (unique balance).',
+      },
+    },
+  },
+};
+
+// Data Binding Examples
+export const DataBindingBasic: Story = {
+  render: () => (
+    <QwickApp appId="heroblock-data-binding" appName='HeroBlock Data Binding'>
+      <DataProvider dataSource={{ dataProvider }}>
+        <Box>
+          
+          <Box sx={{ p: 4, backgroundColor: 'background.paper' }}>
+            <Typography variant="h5" gutterBottom>📊 Data-Driven HeroBlock</Typography>
+            <Typography variant="body1" sx={{ mb: 3, opacity: 0.8 }}>
+              HeroBlock components can be driven entirely by CMS data using the dataSource prop.
+            </Typography>
+            
+            <Code title="Usage" language="tsx">{`<HeroBlock dataSource="heroes.home" />`}</Code>
+            
+            <Code title="Data Structure" language="json">{JSON.stringify(sampleCmsData.heroes.home, null, 2)}</Code>
+          </Box>
+
+          <HeroBlock dataSource="heroes.home" />
+          
+        </Box>
+      </DataProvider>
+    </QwickApp>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'HeroBlock with data binding - all props resolved from CMS data through dataSource.',
+      },
+    },
+  },
+};
+
+export const DataBindingAdvanced: Story = {
+  render: () => (
+    <QwickApp appId="heroblock-data-advanced" appName='Advanced HeroBlock Data Binding'>
+      <DataProvider dataSource={{ dataProvider }}>
+        <Box>
+          
+          <Box sx={{ p: 4, backgroundColor: 'background.paper' }}>
+            <Typography variant="h5" gutterBottom>🎯 Multiple Data Sources</Typography>
+            <Typography variant="body1" sx={{ mb: 3, opacity: 0.8 }}>
+              Different HeroBlock components can pull from different data sources with varying configurations.
+            </Typography>
+          </Box>
+
+          {/* Product Launch Hero */}
+          <HeroBlock dataSource="heroes.product-launch" />
+          
+          {/* About Hero */}
+          <HeroBlock dataSource="heroes.about" />
+          
+          {/* Minimal Hero */}
+          <HeroBlock dataSource="heroes.minimal" />
+          
+        </Box>
+      </DataProvider>
+    </QwickApp>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Advanced data binding with multiple data sources showcasing different hero styles and configurations.',
+      },
+    },
+  },
+};
+
+export const DataBindingWithFallback: Story = {
+  render: () => (
+    <QwickApp appId="heroblock-fallback" appName='HeroBlock Data Binding with Fallback'>
+      <DataProvider dataSource={{ dataProvider }}>
+        <Box>
+          
+          <Box sx={{ p: 4, backgroundColor: 'background.paper' }}>
+            <Typography variant="h5" gutterBottom>🛡️ Fallback Support</Typography>
+            <Typography variant="body1" sx={{ mb: 3, opacity: 0.8 }}>
+              HeroBlock components gracefully handle missing data sources with fallback props.
+            </Typography>
+            
+            <Code title="Fallback Usage" language="tsx">{`<HeroBlock 
+  dataSource="nonexistent.hero" 
+  title="Fallback Hero Title"
+  subtitle="Shows when data source is missing"
+  backgroundColor="default"
+/>`}</Code>
+          </Box>
+
+          <HeroBlock 
+            dataSource="nonexistent.hero"
+            title="Fallback Hero Content"
+            subtitle="This hero appears when the dataSource doesn't exist, ensuring your page never breaks"
+            backgroundColor="default"
+            blockHeight="medium"
+            textAlign="center"
+            actions={[
+              { label: 'Fallback Action', variant: 'primary' }
+            ]}
+          />
+          
+        </Box>
+      </DataProvider>
+    </QwickApp>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'HeroBlock with fallback props when dataSource is missing or unavailable.',
+      },
+    },
+  },
+};
+
+export const RealWorldExample: Story = {
+  render: () => (
+    <QwickApp appId="heroblock-real-world" appName='Real World HeroBlock Example'>
+      <DataProvider dataSource={{ dataProvider }}>
+        <Box>
+          
+          {/* Main Hero - Data Driven */}
+          <HeroBlock dataSource="heroes.home" />
+          
+          {/* Product Launch Hero - Data Driven */}
+          <HeroBlock dataSource="heroes.product-launch">
+            <Typography sx={{ 
+              mt: 3, 
+              fontSize: '1.1rem', 
+              maxWidth: '600px', 
+              opacity: 0.9,
+              fontWeight: 500 
+            }}>
+              Join thousands of developers who have already transformed their workflow
+            </Typography>
+          </HeroBlock>
+          
+          {/* About Hero - Traditional Props with Custom Content */}
+          <HeroBlock
+            title="Ready to Get Started?"
+            subtitle="Join our community and start building amazing applications today"
+            backgroundColor="primary"
+            blockHeight="medium"
+            textAlign="center"
+            actions={[
+              { label: 'Create Account', variant: 'primary', buttonSize: 'large' },
+              { label: 'Browse Examples', variant: 'text', buttonSize: 'large' }
+            ]}
+          >
+            <Box sx={{ 
+              mt: 4, 
+              display: 'flex', 
+              justifyContent: 'center', 
+              gap: 4, 
+              flexWrap: 'wrap',
+              opacity: 0.9 
+            }}>
+              <Box sx={{ textAlign: 'center' }}>
+                <Typography variant="h4" sx={{ fontWeight: 'bold' }}>10k+</Typography>
+                <Typography>Developers</Typography>
+              </Box>
+              <Box sx={{ textAlign: 'center' }}>
+                <Typography variant="h4" sx={{ fontWeight: 'bold' }}>500+</Typography>
+                <Typography>Companies</Typography>
+              </Box>
+              <Box sx={{ textAlign: 'center' }}>
+                <Typography variant="h4" sx={{ fontWeight: 'bold' }}>99.9%</Typography>
+                <Typography>Uptime</Typography>
+              </Box>
+            </Box>
+          </HeroBlock>
+          
+        </Box>
+      </DataProvider>
+    </QwickApp>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Real-world example combining data-driven HeroBlocks with traditional usage and custom child content.',
+      },
+    },
+  },
+};

package/src/stories/Html.stories.tsx

@@ -0,0 +1,264 @@
+/**
+ * Html Component Stories
+ * 
+ * Demonstrates HTML transformation capabilities of the Html component.
+ */
+
+import type { Meta, StoryObj } from '@storybook/react';
+import { Html } from '../components/Html';
+
+const meta: Meta<typeof Html> = {
+  title: 'Components/Html',
+  component: Html,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component: 'The Html component transforms HTML strings into Framework components using configurable transformation rules. Perfect for rendering dynamic HTML content from data sources with Framework component styling.',
+      },
+    },
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    children: {
+      control: 'text',
+      description: 'HTML content as string',
+    },
+    stripHeaders: {
+      control: 'boolean',
+      description: 'Whether to strip header elements (useful for articles)',
+    },
+    sanitize: {
+      control: 'boolean',
+      description: 'Whether to sanitize HTML content',
+    },
+    placeholder: {
+      control: 'text',
+      description: 'Fallback content when HTML is empty',
+    },
+    component: {
+      control: 'text',
+      description: 'Container element type',
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Html>;
+
+export const BasicContent: Story = {
+  args: {
+    children: '<h2>Welcome to QwickApps</h2><p>This is a <strong>basic example</strong> of HTML content being transformed into Framework components.</p><p>Notice how the styling automatically matches the theme.</p>',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Basic HTML content with headings and paragraphs. The component automatically applies Framework styling.',
+      },
+    },
+  },
+};
+
+export const CodeBlocks: Story = {
+  args: {
+    children: `
+      <h3>Code Transformation Examples</h3>
+      <p>Here's a JavaScript code block:</p>
+      <pre><code class="language-javascript">
+function greet(name) {
+  console.log(\`Hello, \${name}!\`);
+}
+
+greet("World");
+      </code></pre>
+      <p>And here's some inline <code>const x = 42</code> code.</p>
+      <p>Multi-line code blocks are transformed too:</p>
+      <code>
+const users = [
+  { name: "Alice", age: 30 },
+  { name: "Bob", age: 25 }
+];
+      </code>
+    `,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Code blocks are automatically transformed into the Framework Code component with syntax highlighting and copy functionality.',
+      },
+    },
+  },
+};
+
+export const BlogSections: Story = {
+  args: {
+    children: `
+      <section class="blog-section" data-padding="large">
+        <h2>Introduction</h2>
+        <p>This section demonstrates how blog sections are transformed into Framework Section components.</p>
+      </section>
+      
+      <section class="blog-section" data-padding="medium">
+        <h2>Features</h2>
+        <ul>
+          <li>Automatic spacing control via data-padding</li>
+          <li>Section titles become Typography components</li>
+          <li>Content is properly contained and styled</li>
+        </ul>
+      </section>
+    `,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Blog sections with class="blog-section" are transformed into Framework Section components with configurable padding.',
+      },
+    },
+  },
+};
+
+export const InteractiveElements: Story = {
+  args: {
+    children: `
+      <h3>Interactive Elements</h3>
+      <p>Buttons are transformed into Framework Button components:</p>
+      <button data-variant="contained">Primary Action</button>
+      <button data-variant="outlined">Secondary Action</button>
+      <button disabled>Disabled Button</button>
+      
+      <p>Other elements maintain their HTML structure but get Framework styling:</p>
+      <blockquote>
+        This is a blockquote that will be styled according to the current theme.
+      </blockquote>
+    `,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Interactive elements like buttons are transformed into Framework components while maintaining their functionality.',
+      },
+    },
+  },
+};
+
+export const HeaderStripping: Story = {
+  args: {
+    children: `
+      <header class="blog-header">
+        <h1>Article Title</h1>
+        <p>This header will be stripped when stripHeaders=true</p>
+      </header>
+      
+      <h1>Standalone H1</h1>
+      <p>This standalone H1 will also be removed when stripHeaders=true</p>
+      
+      <h2>Main Content</h2>
+      <p>This content will always be preserved.</p>
+    `,
+    stripHeaders: true,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'When stripHeaders is enabled, blog headers and standalone H1 elements are removed. Useful for articles where headers are handled separately.',
+      },
+    },
+  },
+};
+
+export const EmptyContent: Story = {
+  args: {
+    children: '',
+    placeholder: 'No content available at this time.',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'When no content is provided, a placeholder message can be shown with appropriate styling.',
+      },
+    },
+  },
+};
+
+export const CustomContainer: Story = {
+  args: {
+    children: '<h2>Article Title</h2><p>This content is rendered inside an article element instead of the default div.</p>',
+    component: 'article',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'The container element can be customized using the component prop.',
+      },
+    },
+  },
+};
+
+export const ComplexContent: Story = {
+  args: {
+    children: `
+      <article>
+        <h1>Complete Article Example</h1>
+        
+        <section class="blog-section" data-padding="large">
+          <h2>Introduction</h2>
+          <p>This is a comprehensive example showing various HTML elements being transformed.</p>
+          
+          <pre><code class="language-typescript">
+interface HtmlProps {
+  children: string;
+  transformConfig?: TransformConfig;
+  stripHeaders?: boolean;
+  sanitize?: boolean;
+}
+          </code></pre>
+        </section>
+        
+        <section class="blog-section" data-padding="medium">
+          <h2>Key Features</h2>
+          <ul>
+            <li><strong>Code Highlighting:</strong> Automatic syntax highlighting for code blocks</li>
+            <li><strong>Button Components:</strong> HTML buttons become Framework buttons</li>
+            <li><strong>Section Management:</strong> Blog sections get proper spacing and layout</li>
+            <li><strong>Theme Integration:</strong> All content respects the current theme</li>
+          </ul>
+          
+          <p>Try these interactive elements:</p>
+          <button data-variant="contained">Get Started</button>
+          <button data-variant="outlined">Learn More</button>
+        </section>
+        
+        <blockquote>
+          <p>"The Html component makes it easy to render dynamic content while maintaining consistent Framework styling and behavior."</p>
+        </blockquote>
+      </article>
+    `,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'A complex example demonstrating multiple transformation rules working together in a single HTML document.',
+      },
+    },
+  },
+};
+
+export const SanitizedContent: Story = {
+  args: {
+    children: `
+      <h3>Sanitized Content Example</h3>
+      <p>This content includes potentially dangerous elements that are sanitized:</p>
+      <script>alert('This would be dangerous!');</script>
+      <p onclick="alert('Click handler')">This paragraph has an onclick handler that will be removed.</p>
+      <p>But this <strong>safe content</strong> is preserved perfectly.</p>
+      <p>Links are also handled safely: <a href="https://qwickapps.com">Visit QwickApps</a></p>
+    `,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'HTML content is automatically sanitized to remove dangerous elements and attributes while preserving safe content.',
+      },
+    },
+  },
+};