klz-cables.com/components/content/README.md

# Content Components

Modern, component-based content rendering system for WordPress migration to Next.js. These components handle WordPress content display in a responsive, accessible, and SEO-friendly way.

## Components Overview

### 1. Hero Component (`Hero.tsx`)
Full-width hero section with background image support, overlays, and CTAs.

**Features:**
- Background images with Next.js Image optimization
- Text overlay for readability
- Multiple height options (sm, md, lg, xl, full)
- Optional CTA button
- Responsive sizing
- Variant support (default, dark, primary, gradient)

**Usage:**
```tsx
import { Hero } from '@/components/content';

<Hero
  title="Welcome to KLZ Cables"
  subtitle="High-quality cable solutions for industrial applications"
  backgroundImage="/media/hero-image.jpg"
  height="lg"
  variant="dark"
  overlay
  overlayOpacity={0.6}
  ctaText="Learn More"
  ctaLink="/products"
/>
```

### 2. ContentRenderer Component (`ContentRenderer.tsx`)
Sanitizes and renders HTML content from WordPress with class conversion.

**Features:**
- HTML sanitization (removes scripts, styles, dangerous attributes)
- WordPress class to Tailwind conversion
- Next.js Image component integration
- Shortcode processing
- Safe HTML parsing
- SEO-friendly markup

**Usage:**
```tsx
import { ContentRenderer } from '@/components/content';

<ContentRenderer 
  content={page.contentHtml}
  sanitize={true}
  processAssets={true}
  convertClasses={true}
/>
```

**Supported HTML Elements:**
- Typography: `<p>`, `<h1-h6>`, `<strong>`, `<em>`, `<small>`
- Lists: `<ul>`, `<ol>`, `<li>`
- Links: `<a>` (with Next.js Link optimization)
- Images: `<img>` (with Next.js Image)
- Tables: `<table>`, `<thead>`, `<tbody>`, `<tr>`, `<th>`, `<td>`
- Layout: `<div>`, `<span>`, `<section>`, `<article>`, `<figure>`, `<figcaption>`
- Code: `<code>`, `<pre>`
- Quotes: `<blockquote>`

### 3. FeaturedImage Component (`FeaturedImage.tsx`)
Optimized image display with responsive sizing and lazy loading.

**Features:**
- Next.js Image optimization
- Lazy loading
- Aspect ratio control
- Caption support
- Alt text handling
- Priority loading option

**Usage:**
```tsx
import { FeaturedImage } from '@/components/content';

<FeaturedImage
  src="/media/product.jpg"
  alt="Product image"
  aspectRatio="16:9"
  size="lg"
  caption="Product overview"
  priority={false}
/>
```

**Aspect Ratios:**
- `1:1` - Square
- `4:3` - Standard
- `16:9` - Widescreen
- `21:9` - Ultrawide
- `auto` - Natural

**Sizes:**
- `sm` - max-w-xs
- `md` - max-w-md
- `lg` - max-w-lg
- `xl` - max-w-xl
- `full` - max-w-full

### 4. Section Component (`Section.tsx`)
Wrapper for content sections with background and padding options.

**Features:**
- Background color variants
- Padding options
- Container integration
- Full-width support
- Semantic HTML

**Usage:**
```tsx
import { Section, SectionHeader, SectionContent } from '@/components/content';

<Section background="light" padding="xl">
  <SectionHeader 
    title="Our Products" 
    subtitle="Browse our extensive catalog"
    align="center"
  />
  <SectionContent>
    {/* Your content here */}
  </SectionContent>
</Section>
```

**Background Options:**
- `default` - White
- `light` - Light gray
- `dark` - Dark gray with white text
- `primary` - Primary color with white text
- `secondary` - Secondary color with white text
- `gradient` - Gradient from primary to secondary

**Padding Options:**
- `none` - No padding
- `sm` - Small
- `md` - Medium
- `lg` - Large
- `xl` - Extra large
- `2xl` - Double extra large

### 5. Breadcrumbs Component (`Breadcrumbs.tsx`)
SEO-friendly breadcrumb navigation with schema.org markup.

**Features:**
- Schema.org structured data
- Home icon
- Responsive (collapses on mobile)
- Customizable separators
- Multiple variants

**Usage:**
```tsx
import { Breadcrumbs } from '@/components/content';

<Breadcrumbs
  items={[
    { label: 'Home', href: '/' },
    { label: 'Products', href: '/products' },
    { label: 'Cables', href: '/products/cables' },
    { label: 'Current Page' }
  ]}
  separator="/"
  showHome={true}
  collapseMobile={true}
/>
```

**Variants:**
- `BreadcrumbsCompact` - Minimal design
- `BreadcrumbsSimple` - Basic navigation

## Integration with WordPress Data

All components are designed to work seamlessly with the WordPress data layer:

```tsx
import { 
  Hero, 
  Section, 
  ContentRenderer, 
  FeaturedImage,
  Breadcrumbs 
} from '@/components/content';
import { getPageBySlug, getMediaById } from '@/lib/data';

export default async function Page({ params }) {
  const page = getPageBySlug(params.slug, params.locale);
  const featuredMedia = page.featuredImage ? getMediaById(page.featuredImage) : null;

  return (
    <>
      <Breadcrumbs
        items={[
          { label: 'Home', href: `/${params.locale}` },
          { label: page.title }
        ]}
      />
      
      <Hero
        title={page.title}
        backgroundImage={featuredMedia?.localPath}
        height="md"
      />
      
      <Section padding="xl">
        <ContentRenderer content={page.contentHtml} />
      </Section>
    </>
  );
}
```

## WordPress Class Conversion

The ContentRenderer automatically converts common WordPress/Salient classes to Tailwind:

| WordPress Class | Tailwind Equivalent |
|----------------|---------------------|
| `vc_row` | `flex flex-wrap -mx-4` |
| `vc_col-md-6` | `w-full md:w-1/2 px-4` |
| `vc_col-md-4` | `w-full md:w-1/3 px-4` |
| `text-center` | `text-center` |
| `bg-light` | `bg-gray-50` |
| `btn btn-primary` | `inline-flex items-center justify-center px-4 py-2 rounded-lg font-semibold bg-primary text-white hover:bg-primary-dark` |
| `wpb_wrapper` | `space-y-4` |
| `accent-color` | `text-primary` |

## Security Features

All components include security measures:

1. **HTML Sanitization**: Removes scripts, styles, and dangerous attributes
2. **URL Validation**: Validates and sanitizes all URLs
3. **XSS Prevention**: Removes inline event handlers and javascript: URLs
4. **Safe Parsing**: Only allows safe HTML elements and attributes
5. **Asset Validation**: Validates image sources and dimensions

## Performance Optimization

- **Lazy Loading**: Images load only when needed
- **Next.js Image**: Automatic optimization and WebP support
- **Priority Loading**: Critical images can be preloaded
- **Efficient Rendering**: Memoized processing for large content
- **Responsive Images**: Proper `sizes` attribute for different viewports

## Internationalization

All components support internationalization:

```tsx
<Hero
  title={t('hero.title')}
  subtitle={t('hero.subtitle')}
  ctaText={t('hero.cta')}
/>
```

## Accessibility

- Semantic HTML elements
- Proper heading hierarchy
- Alt text for images
- ARIA labels where needed
- Keyboard navigation support
- Screen reader friendly

## Customization

All components accept `className` props for custom styling:

```tsx
<Hero
  title="Custom Hero"
  className="custom-hero-class"
  // ... other props
/>
```

## TypeScript Support

All components include full TypeScript definitions:

```tsx
import { HeroProps, SectionProps } from '@/components/content';

const heroConfig: HeroProps = {
  title: 'My Hero',
  height: 'lg',
  // TypeScript will guide you through all options
};
```

## Best Practices

1. **Always provide alt text** for images
2. **Use priority** for above-the-fold images
3. **Sanitize content** from untrusted sources
4. **Process assets** to ensure local file availability
5. **Convert classes** for consistent styling
6. **Add breadcrumbs** for SEO and navigation
7. **Use semantic sections** for content structure

## Migration Notes

When migrating from WordPress:

1. Export content with `contentHtml` fields
2. Download and host media files locally
3. Map WordPress URLs to local paths
4. Test class conversion for custom themes
5. Verify shortcodes are processed or removed
6. Check responsive behavior on all devices
7. Validate SEO markup (schema.org)

## Component Composition

Components can be composed together:

```tsx
<Section background="dark" padding="xl">
  <div className="text-center text-white">
    <h2 className="text-3xl font-bold mb-4">Featured Products</h2>
    <div className="grid grid-cols-1 md:grid-cols-3 gap-6 mt-8">
      {products.map(product => (
        <Card key={product.id}>
          <FeaturedImage 
            src={product.image} 
            alt={product.name}
            aspectRatio="4:3"
          />
          <CardBody>
            <h3>{product.name}</h3>
            <ContentRenderer content={product.description} />
          </CardBody>
        </Card>
      ))}
    </div>
  </div>
</Section>
```

This creates a cohesive, modern content system that maintains WordPress flexibility while leveraging Next.js capabilities.