@qwickapps/react-framework 1.3.0

package/README.md

@@ -0,0 +1,794 @@
+# QwickApps React Framework
+
+A complete React framework for building modern, responsive applications with intelligent navigation, flexible layouts, and a comprehensive theming system.
+
+## What's New
+
+### August 31, 2025 - CMS Content Components
+- **Html Component**: Transform HTML strings into React components with configurable transformation rules
+- **Markdown Component**: Convert Markdown to React components using marked library with Html component integration
+- **Transform System**: Extensible HTML transformation architecture with optimized rule sets for Article and Markdown content
+- **Content Simplification**: Article and Content components refactored to use Html component internally, eliminating duplicate transformation logic
+
+## Features
+
+### 🧭 **Responsive Navigation**
+- **Mobile**: Bottom navigation bar for touch-friendly access
+- **Tablet**: Expandable nav rail with collapsible sidebar
+- **Desktop**: Top navigation with overflow drawer
+- **Automatic**: Adapts based on screen size without configuration
+
+### 📐 **Flexible Layout System**
+- **Hero Blocks**: Full-width hero sections with background images/gradients
+- **Multi-Column Layouts**: Responsive 2-5 column layouts with equal heights
+- **Content Blocks**: Styled containers with variants (elevated, outlined, filled)
+- **Feature Grids**: Showcase features with icons, titles, and actions
+- **Section Containers**: Configurable spacing and background variants
+
+### 🎨 **Advanced Theming**
+- **Theme Management**: Light, dark, and system theme support
+- **Color Palettes**: Multiple built-in palettes (Ocean, Autumn, Spring, Winter)
+- **CSS Variables**: Dynamic theme switching without re-renders
+- **Custom Palettes**: Easy to create and integrate custom color schemes
+
+### 🧩 **Component Library**
+- **Logo Component**: Dynamic, customizable logos with badges and animations
+- **Theme Controls**: Built-in theme and palette switchers
+- **Form Components**: Accessible, themed form inputs
+- **Safe Components**: XSS-protected content rendering
+- **Html Component**: Transform HTML strings to React components with configurable rules
+- **Markdown Component**: Convert Markdown to React components with syntax highlighting
+- **Transform System**: Extensible HTML element transformation with fallback handling
+
+### 🚀 **Developer Experience**
+- **TypeScript First**: Full TypeScript support with comprehensive types
+- **Storybook**: Interactive component documentation
+- **Performance**: Optimized rendering and minimal bundle size
+- **Accessibility**: WCAG-compliant components with ARIA support
+
+## Installation
+
+```bash
+npm install @qwickapps/react-framework
+```
+
+## Quick Start
+
+### Basic Setup
+
+```tsx
+import { 
+  QwickApp, 
+  ResponsiveMenu, 
+  HeroBlock,
+  Section,
+  Content 
+} from '@qwickapps/react-framework';
+
+const menuItems = [
+  {
+    id: 'home',
+    label: 'Home',
+    icon: <HomeIcon />,
+    onClick: () => navigate('/'),
+    active: true,
+  },
+  {
+    id: 'about',
+    label: 'About',
+    icon: <InfoIcon />,
+    onClick: () => navigate('/about'),
+  },
+];
+
+function App() {
+  return (
+    <QwickApp appName="MyApp" appId="com.mycompany.app">
+      <ResponsiveMenu items={menuItems} />
+      
+      <HeroBlock
+        title="Welcome to MyApp"
+        subtitle="Build amazing applications with ease"
+        backgroundGradient="linear-gradient(135deg, #667eea 0%, #764ba2 100%)"
+        actions={
+          <button>Get Started</button>
+        }
+      />
+      
+      <Section padding="large">
+        <Content title="About Us" centered>
+          <p>Your content here...</p>
+        </Content>
+      </Section>
+    </QwickApp>
+  );
+}
+```
+
+### Custom Logo
+
+```tsx
+// Use built-in Logo component with appName
+<QwickApp appName="MyApp" />
+
+// Or provide a custom logo
+<QwickApp 
+  appName="MyApp"
+  logo={<img src="/logo.png" alt="MyApp" />}
+/>
+
+// Custom logo with built-in Logo component
+<QwickApp 
+  appName="MyApp"
+  logo={<Logo name="MyApp" size="large" badge="top-right" />}
+/>
+```
+
+## Responsive Navigation
+
+The `ResponsiveMenu` component automatically adapts to different screen sizes:
+
+```tsx
+import { ResponsiveMenu } from '@qwickapps/react-framework';
+
+const menuItems = [
+  {
+    id: 'dashboard',
+    label: 'Dashboard',
+    icon: <DashboardIcon />,
+    onClick: () => navigate('/dashboard'),
+    active: true,
+  },
+  {
+    id: 'products',
+    label: 'Products', 
+    icon: <ProductsIcon />,
+    onClick: () => navigate('/products'),
+    badge: '5', // Show badge with count
+  },
+  {
+    id: 'settings',
+    label: 'Settings',
+    icon: <SettingsIcon />,
+    href: '/settings', // Use href for links
+    disabled: false,
+  },
+];
+
+function App() {
+  return (
+    <QwickApp appName="MyApp">
+      <ResponsiveMenu 
+        items={menuItems}
+        logoPosition="center" // 'left' | 'center' | 'right'
+        onMenuToggle={(isOpen) => console.log('Menu state:', isOpen)}
+      />
+      {/* Your content */}
+    </QwickApp>
+  );
+}
+```
+
+**Responsive Behavior:**
+- **Mobile (< 768px)**: Bottom navigation bar
+- **Tablet (768-1024px)**: Collapsible sidebar nav rail  
+- **Desktop (> 1024px)**: Top navigation with drawer for overflow
+
+## Layout Blocks
+
+Build flexible, responsive layouts with pre-built components:
+
+### Hero Blocks
+
+```tsx
+import { HeroBlock } from '@qwickapps/react-framework';
+
+<HeroBlock
+  title="Welcome to Our Platform"
+  subtitle="The best way to manage your workflow"
+  height="large" // 'small' | 'medium' | 'large' | 'fullscreen'
+  backgroundImage="/hero-bg.jpg"
+  backgroundGradient="linear-gradient(135deg, #667eea 0%, #764ba2 100%)"
+  overlayOpacity={0.6}
+  textAlign="center"
+  actions={
+    <div>
+      <button>Get Started</button>
+      <button>Learn More</button>
+    </div>
+  }
+/>
+```
+
+### Multi-Column Layouts
+
+```tsx
+import { GridLayout, GridCell } from '@qwickapps/react-framework';
+
+<GridLayout columns={3} spacing="large" equalHeight responsive>
+  <GridCell padding="large" background="var(--theme-surface)">
+    <h3>Feature One</h3>
+    <p>Description here...</p>
+  </GridCell>
+  <GridCell padding="large" background="var(--theme-surface)">
+    <h3>Feature Two</h3>
+    <p>More content...</p>
+  </GridCell>
+  <GridCell padding="large" background="var(--theme-surface)">
+    <h3>Feature Three</h3>
+    <p>Even more content...</p>
+  </GridCell>
+</GridLayout>
+```
+
+### Feature Grids
+
+```tsx
+import { FeatureGrid } from '@qwickapps/react-framework';
+
+<FeatureGrid
+  columns={3}
+  gap="large"
+  features={[
+    {
+      id: 'fast',
+      icon: <FastIcon />,
+      title: 'Lightning Fast',
+      description: 'Optimized for performance and speed',
+      action: <button>Learn More</button>
+    },
+    {
+      id: 'secure',
+      icon: <SecureIcon />,
+      title: 'Secure by Default',
+      description: 'Built with security best practices',
+      action: <button>Security Guide</button>
+    },
+    {
+      id: 'scalable',
+      icon: <ScaleIcon />,
+      title: 'Highly Scalable',
+      description: 'Grows with your application needs',
+      action: <button>Architecture</button>
+    },
+  ]}
+/>
+```
+
+### Content Blocks & Sections
+
+```tsx
+import { Section, Content } from '@qwickapps/react-framework';
+
+<Section padding="large" background="alternate" maxWidth="large">
+  <Content 
+    title="About Our Company"
+    variant="elevated" // 'default' | 'elevated' | 'outlined' | 'filled'
+    padding="large"
+    centered
+  >
+    <p>Your content here...</p>
+  </Content>
+</Section>
+```
+
+## CMS Content Components
+
+Transform HTML strings and Markdown content into React components with intelligent element transformation and syntax highlighting.
+
+### Html Component
+
+Transform HTML strings into React components with configurable transformation rules:
+
+```tsx
+import { Html } from '@qwickapps/react-framework';
+
+// Basic HTML transformation
+<Html>
+  {`<h1>Welcome</h1>
+    <p>This is a paragraph with <code>inline code</code>.</p>
+    <pre><code class="language-javascript">
+      const greeting = "Hello, World!";
+      console.log(greeting);
+    </code></pre>`}
+</Html>
+
+// Custom transformation rules
+const customRules = [
+  {
+    selector: 'button',
+    transform: (element, key) => (
+      <Button key={key} variant="contained">
+        {element.textContent}
+      </Button>
+    )
+  }
+];
+
+<Html transformConfig={{ rules: customRules }}>
+  {htmlContent}
+</Html>
+
+// With header stripping (useful for articles)
+<Html stripHeaders placeholder="No content available">
+  {articleContent}
+</Html>
+```
+
+**Default Transformations:**
+- `<pre><code>` → Code component with syntax highlighting
+- `<section class="blog-section">` → Section component
+- `<button>` → Button component
+- Other elements → Native HTML with SafeSpan content
+
+### Markdown Component
+
+Convert Markdown to React components with full GitHub Flavored Markdown support:
+
+```tsx
+import { Markdown } from '@qwickapps/react-framework';
+
+const markdownContent = `
+# Welcome to Our Platform
+
+This is **bold text** and this is *italic text*.
+
+## Code Example
+
+Here's some JavaScript:
+
+\`\`\`javascript
+const framework = "QwickApps";
+console.log(\`Using \${framework} Framework\`);
+\`\`\`
+
+And some inline \`code\` here.
+
+## Features
+
+- React components
+- Syntax highlighting  
+- GitHub Flavored Markdown
+- Configurable transformation
+`;
+
+<Markdown>{markdownContent}</Markdown>
+
+// With custom HTML transformation config
+<Markdown htmlTransformConfig={customConfig}>
+  {markdownContent}
+</Markdown>
+
+// With placeholder for empty content
+<Markdown placeholder="No content to display">
+  {emptyContent}
+</Markdown>
+```
+
+**Key Features:**
+- GitHub Flavored Markdown support via marked library
+- Automatic syntax highlighting for code blocks
+- Inline code preservation 
+- Custom transformation rules for HTML elements
+- Error handling with development debugging
+- TypeScript support with comprehensive props interface
+
+### Transform System Architecture
+
+The transform system provides extensible HTML element transformation:
+
+```tsx
+import { TransformRule, TransformConfig } from '@qwickapps/react-framework';
+
+// Define custom transformation rules
+const articleRules: TransformRule[] = [
+  {
+    selector: 'pre',
+    transform: (element, key) => {
+      const codeChild = element.querySelector('code');
+      if (!codeChild) return null;
+      
+      const language = Array.from(codeChild.classList)
+        .find(cls => cls.startsWith('language-'))
+        ?.replace('language-', '') || 'text';
+      
+      return (
+        <Code key={key} language={language} showCopy>
+          {codeChild.textContent || ''}
+        </Code>
+      );
+    }
+  },
+  // Add more rules...
+];
+
+const config: TransformConfig = {
+  rules: articleRules,
+  sanitize: true,
+  fallbackComponent: (element, key) => (
+    <SafeSpan key={key} html={element.outerHTML} />
+  )
+};
+
+// Use with Html or Markdown components
+<Html transformConfig={config}>{htmlContent}</Html>
+<Markdown htmlTransformConfig={config}>{markdownContent}</Markdown>
+```
+
+**Built-in Rule Sets:**
+- `defaultArticleRules` - Optimized for blog/article content with header stripping
+- `defaultMarkdownRules` - Optimized for Markdown content with inline code preservation
+
+### Integration with Existing Components
+
+The Html and Markdown components integrate seamlessly with existing Framework components:
+
+```tsx
+// Article component now uses Html internally
+<Article title="Blog Post" author="John Doe">
+  {htmlContent} {/* Automatically transformed via Html component */}
+</Article>
+
+// Content component detects string children and uses Html
+<Content title="Dynamic Content">
+  {dynamicHtmlFromCMS} {/* String content automatically transformed */}
+</Content>
+
+// Section with Markdown content
+<Section padding="large">
+  <Content title="Documentation">
+    <Markdown>{documentationMarkdown}</Markdown>
+  </Content>
+</Section>
+```
+
+### Error Handling and Fallbacks
+
+Both components provide comprehensive error handling:
+
+```tsx
+// Development mode shows detailed errors
+<Html>{malformedHtml}</Html> // Shows red border with error details
+
+// Production mode gracefully degrades
+<Markdown>{invalidMarkdown}</Markdown> // Falls back to SafeSpan rendering
+
+// Custom error handling
+<Html 
+  placeholder="Content temporarily unavailable"
+  fallbackComponent={(element, key) => (
+    <div key={key}>Custom fallback for {element.tagName}</div>
+  )}
+>
+  {riskyContent}
+</Html>
+```
+
+## Theming System
+
+### Theme Modes
+
+```tsx
+import { useTheme } from '@qwickapps/react-framework';
+
+function ThemeControls() {
+  const { themeMode, switchTheme } = useTheme();
+  
+  return (
+    <div>
+      <button onClick={() => switchTheme('light')}>Light</button>
+      <button onClick={() => switchTheme('dark')}>Dark</button>
+      <button onClick={() => switchTheme('system')}>System</button>
+      <p>Current theme: {themeMode}</p>
+    </div>
+  );
+}
+```
+
+### Color Palettes
+
+```tsx
+import { usePalette } from '@qwickapps/react-framework';
+
+function PaletteControls() {
+  const { currentPalette, switchPalette } = usePalette();
+  
+  return (
+    <div>
+      <button onClick={() => switchPalette('ocean')}>Ocean</button>
+      <button onClick={() => switchPalette('autumn')}>Autumn</button>
+      <button onClick={() => switchPalette('spring')}>Spring</button>
+      <button onClick={() => switchPalette('winter')}>Winter</button>
+      <p>Current palette: {currentPalette}</p>
+    </div>
+  );
+}
+```
+
+### CSS Variables
+
+The framework exposes CSS custom properties for consistent theming:
+
+```css
+.my-component {
+  background: var(--theme-surface);
+  color: var(--theme-on-surface);
+  border: 1px solid var(--theme-border-main);
+}
+
+.primary-button {
+  background: var(--theme-primary);
+  color: var(--theme-on-primary);
+  border-radius: var(--theme-border-radius);
+}
+```
+
+**Available Variables:**
+- `--theme-primary`, `--theme-on-primary`
+- `--theme-secondary`, `--theme-on-secondary`
+- `--theme-surface`, `--theme-on-surface`
+- `--theme-background`, `--theme-on-background`
+- `--theme-outline`, `--theme-outline-variant`
+- `--theme-elevation-1`, `--theme-elevation-2`
+
+## Component API
+
+### QwickApp
+
+```tsx
+interface QwickAppProps {
+  children: React.ReactNode;
+  appId?: string | true | false; // Storage key strategy
+  appName?: string; // Display name for built-in Logo
+  logo?: React.ReactNode; // Custom logo component
+  className?: string;
+  style?: React.CSSProperties;
+  defaultTheme?: 'light' | 'dark' | 'system';
+  defaultPalette?: string;
+}
+```
+
+### ResponsiveMenu
+
+```tsx
+interface ResponsiveMenuProps {
+  items: MenuItem[];
+  className?: string;
+  logo?: React.ReactNode;
+  showLogo?: boolean;
+  logoPosition?: 'left' | 'center' | 'right';
+  brandText?: string;
+  onMenuToggle?: (isOpen: boolean) => void;
+}
+
+interface MenuItem {
+  id: string;
+  label: string;
+  icon?: React.ReactNode;
+  onClick?: () => void;
+  href?: string;
+  active?: boolean;
+  disabled?: boolean;
+  badge?: string | number;
+}
+```
+
+### Html Component
+
+```tsx
+interface HtmlProps extends WithBaseProps {
+  children: string;                    // HTML content as string
+  transformConfig?: TransformConfig;   // Custom transformation rules
+  stripHeaders?: boolean;              // Strip header elements (default: false)
+  sanitize?: boolean;                  // Sanitize HTML (default: true)
+  sanitizeOptions?: any;               // Custom sanitization options
+  placeholder?: string;                // Fallback when content is empty
+  component?: React.ElementType;       // Container element (default: 'div')
+}
+```
+
+### Markdown Component
+
+```tsx
+interface MarkdownProps extends WithBaseProps {
+  children: string;                    // Markdown content as string
+  htmlTransformConfig?: TransformConfig; // HTML transformation config
+  sanitize?: boolean;                  // Sanitize HTML output (default: true)
+  sanitizeOptions?: any;               // Custom sanitization options
+  placeholder?: string;                // Fallback when content is empty
+  component?: React.ElementType;       // Container element (default: 'div')
+  markedOptions?: marked.MarkedOptions; // Marked library options
+}
+```
+
+### Transform System
+
+```tsx
+interface TransformRule {
+  selector: string;                    // CSS selector for elements to transform
+  transform: (element: Element, key: string) => React.ReactNode;
+}
+
+interface TransformConfig {
+  rules: TransformRule[];              // Array of transformation rules
+  sanitize?: boolean;                  // Enable HTML sanitization
+  sanitizeOptions?: any;               // Sanitization configuration
+  fallbackComponent?: (element: Element, key: string) => React.ReactNode;
+}
+```
+
+## Advanced Usage
+
+### Custom Layout Composition
+
+```tsx
+function LandingPage() {
+  return (
+    <QwickApp appName="ProductApp">
+      <ResponsiveMenu items={navigationItems} />
+      
+      {/* Hero Section */}
+      <HeroBlock
+        title="Revolutionary Product"
+        subtitle="Transform your workflow today"
+        backgroundGradient="linear-gradient(135deg, #667eea 0%, #764ba2 100%)"
+        height="fullscreen"
+        actions={<CallToActionButtons />}
+      />
+      
+      {/* Features Section */}
+      <Section padding="extra-large" background="alternate">
+        <Content title="Why Choose Us?" centered maxWidth="large">
+          <FeatureGrid columns={3} features={featureData} />
+        </Content>
+      </Section>
+      
+      {/* Content Sections */}
+      <Section padding="extra-large">
+        <GridLayout columns={2} gap="large">
+          <GridCell>
+            <Content title="For Developers" variant="elevated" padding="large">
+              {/* Developer content */}
+            </Content>
+          </GridCell>
+          <GridCell>
+            <Content title="For Businesses" variant="elevated" padding="large">
+              {/* Business content */}
+            </Content>
+          </GridCell>
+        </GridLayout>
+      </Section>
+      
+      {/* CTA Section */}
+      <Section padding="large" background="primary">
+        <Content centered>
+          <CallToActionSection />
+        </Content>
+      </Section>
+    </QwickApp>
+  );
+}
+```
+
+### Accessing App Context
+
+```tsx
+import { useQwickApp } from '@qwickapps/react-framework';
+
+function MyComponent() {
+  const { appName, logo } = useQwickApp();
+  
+  return (
+    <div>
+      <h1>Welcome to {appName}</h1>
+      {logo && <div>{logo}</div>}
+    </div>
+  );
+}
+```
+
+## TypeScript Support
+
+Full TypeScript support with comprehensive type definitions:
+
+```tsx
+import type { 
+  QwickAppProps,
+  ResponsiveMenuProps,
+  MenuItem,
+  HeroBlockProps,
+  ColumnLayoutProps,
+  FeatureItem,
+} from '@qwickapps/react-framework';
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Start Storybook
+npm run storybook
+
+# Run tests
+npm test
+
+# Build package
+npm run build
+```
+
+## Best Practices
+
+### Logging and Debugging
+
+The framework uses the `@qwickapps/logging` package for centralized logging with development insights and zero production impact:
+
+```typescript
+import { loggers, createLogger } from '@qwickapps/react-framework';
+
+// Use framework-specific loggers
+const logger = loggers.navigation;
+logger.debug('Route changed:', path);
+logger.error('Navigation failed:', error);
+
+// Or create custom loggers
+const myLogger = createLogger('MyComponent');
+myLogger.info('Component initialized');
+```
+
+**Key Benefits:**
+- ✅ No boilerplate conditionals
+- ✅ Automatic production silencing
+- ✅ Namespaced for clarity
+- ✅ TypeScript support
+- ✅ Optional complete stripping
+
+**Build Configuration:**
+
+```json
+// package.json - Consumer application
+{
+  "scripts": {
+    "build:dev": "NODE_ENV=development vite build",
+    "build:prod": "NODE_ENV=production STRIP_LOGS=true vite build",
+    "deploy:dev": "npm run build:dev && npm run deploy",
+    "deploy": "npm run build:prod && npm run deploy"
+  }
+}
+```
+
+For complete documentation, see [@qwickapps/logging](../qwickapps-logging/README.md).
+
+### Component Development
+
+1. **Always extend WithBaseProps** for consistent component API
+2. **Use the GridLayout system** for responsive layouts
+3. **Leverage pre-built hooks** like `useBaseProps` for standardization
+4. **Follow the established patterns** in existing components
+
+### Theme and Styling
+
+1. **Use CSS variables** from the theme system
+2. **Support both light and dark modes** by default
+3. **Test with different palettes** to ensure flexibility
+4. **Use t-shirt sizing** (tiny, small, medium, large, huge) for consistency
+
+### Performance
+
+1. **Import only what you need** - the package supports tree shaking
+2. **Use React.memo** for expensive components
+3. **Leverage the built-in performance monitoring** for theme changes
+4. **Consider lazy loading** for large component trees
+
+## License
+
+**This software is proprietary and confidential. Copyright © 2025 QwickApps.com. All rights reserved.**
+
+This package is private and proprietary to QwickApps.com. It is not licensed for public use, modification, or distribution. Access is restricted to authorized QwickApps team members and approved partners only.
+
+## About QwickApps
+
+This framework is part of the QwickApps ecosystem, providing high-quality solutions for educational and productivity applications.
+
+For more information, visit [QwickApps.com](https://qwickapps.com).