Skip to content

COMPONENTS.md

Latest commit

 

History

History
219 lines (181 loc) · 5.72 KB

COMPONENTS.md

File metadata and controls

219 lines (181 loc) · 5.72 KB

Component Conversion Summary

All Nunjucks templates from src/templates/modules have been successfully converted to React components!

✅ Converted Components

Core Layout Components

  1. Banner (Banner.tsx)

    • Full-width image banner with text overlay
    • Responsive font sizing
    • Props: imageSrc, imageAlt, heading

  2. Hero (Hero.tsx)

    • Responsive hero with picture element
    • Different images for mobile/desktop
    • Optional link wrapper
    • Props: imageSrc, mobileImageSrc, imageAlt, heading, href

  3. Tile (Tile.tsx)

    • Square tiles for images or text
    • Multiple color variants (grey, pink, etc.)
    • Support for CTA links
    • Props: content, variant, ctaLink

  4. NavBar (NavBar.tsx)

    • Responsive navigation bar
    • Logo and navigation links
    • Mobile-friendly
    • Props: logoAlt, logoSrc, links

Feature Components

  1. InfoPanel (InfoPanel.tsx)
    • Image background with overlay content
    • Label, heading, description, and CTA
    • Responsive layout that adapts on mobile
    • Props: imageSrc, label, heading, info, link

Navigation Components

  1. Pagination (Pagination.tsx)

    • Navigation for paginated content
    • Previous/Next buttons
    • Page indicator (e.g., "2 of 6")
    • Optional "back to top" link
    • Props: currentPage, totalPages, onPrevious, onNext, showBackToTop

  2. SectionNav (SectionNav.tsx)

    • Horizontal navigation for categories/filters
    • Active state indicator
    • Responsive wrapping
    • Props: links (array with label, href, active)

Content Components

  1. Card (Card.tsx)

    • Reusable card for blog posts, products, or general content
    • Multiple variants (blog, product, default)
    • Image, title, description, and metadata
    • Props: imageSrc, title, description, href, metadata, variant

  2. Grid (Grid.tsx)

    • Responsive grid container for collections
    • Configurable columns (2, 3, or 4)
    • Adjustable gap spacing
    • Optional heading
    • Props: children, columns, gap, heading

Utility Components

  1. BrowserUpgrade (BrowserUpgrade.tsx)
  • Warning banner for outdated browsers
  • Customizable message and link
  • Props: message, upgradeUrl

📦 Component Structure

Each component follows this structure:

ComponentName/
├── ComponentName.tsx          # Main React component
├── ComponentName.types.ts     # TypeScript type definitions
├── ComponentName.module.scss  # Scoped styles
├── ComponentName.stories.tsx  # Storybook stories
└── index.ts                   # Barrel export

🎨 Styling

All components use:

  • SCSS Modules for scoped styling
  • BEM naming convention (preserved from original)
  • Responsive breakpoints from _variables.scss
  • Design tokens for consistency

📚 Storybook Stories

Each component has multiple stories demonstrating:

  • Default usage
  • Different variants/states
  • Edge cases
  • Prop combinations

🔄 Migration from Nunjucks

Before (Nunjucks):

{% extends "layout.njk" %}
{% block content %}
<div class="banner">
  <img class="banner__image" src="...">
  <div class="banner__caption">
    <h2 class="banner__heading">Title</h2>
  </div>
</div>
{% endblock %}

After (React):

import { Banner } from '@j-cam/pattern-library';

<Banner 
  imageSrc="..." 
  heading="Title" 
/>

📋 Templates Not Converted (Reference Only)

These templates were reference/example files and don't need conversion:

  • html-tags.njk - HTML element examples
  • index.njk - Index/home page template
  • post.njk - Blog post layout example
  • post-collection.njk - Blog listing example
  • product.njk - E-commerce product page example
  • product-collection.njk - Product listing example
  • product-info.njk - Product details partial
  • product-options.njk - Product variant selector
  • product-slider.njk - Product image carousel

These can be built by composing the converted components together in your application.

🚀 Usage

Import and use components:

import {
  Banner,
  Hero,
  Tile,
  NavBar,
  InfoPanel,
  Pagination,
  SectionNav,
  BrowserUpgrade,
  Card,
  Grid
} from '@j-cam/pattern-library';
import '@j-cam/pattern-library/styles';

function App() {
  return (
    <>
      <BrowserUpgrade />
      <NavBar 
        logoAlt="Brand" 
        links={[...]} 
      />
      <Hero 
        imageSrc="hero.jpg" 
        heading="Welcome" 
      />
      <SectionNav 
        links={[...]} 
      />
      <Grid columns={3}>
        {items.map(item => (
          <Card {...item} variant="blog" />
        ))}
      </Grid>
      <InfoPanel 
        imageSrc="panel.jpg"
        heading="Feature"
        info="Description..."
        link={{ label: 'Learn more', href: '#' }}
      />
      <Pagination 
        currentPage={1}
        totalPages={5}
      />
    </>
  );
}

🎨 Composed Layouts

The library includes three example layouts showing how to compose components:

HomePage Layout

  • NavBar + Hero + Tiles (2x2 grid) + Banner + InfoPanel
  • Perfect for: Landing pages, marketing sites, portfolios

BlogPage Layout

  • NavBar + Hero + SectionNav + Grid of Cards + Pagination
  • Perfect for: Blogs, news sites, article listings

ShopPage Layout

  • NavBar + Banner + SectionNav + Multiple Grids + InfoPanel
  • Perfect for: E-commerce, product catalogs, online stores

See LAYOUTS.md for detailed examples and composition patterns.

✨ Next Steps

  1. Install dependencies: npm install
  2. Start Storybook: npm run dev
  3. Explore components: Browse all components at http://localhost:6006
  4. Build library: npm run build when ready to publish

All components are fully typed, documented, and ready to use!