E4 Component Library

Moderní React component library pro Next.js aplikace. Postavena na Storybook 10, TypeScript a SCSS Modules s plnou podporou themování.

📖 Live Storybook dokumentace

📦 Dostupné komponenty

Source taxonomy (src/components/ui/ vs src/components/patterns/) is defined in docs/COMPONENT_GUIDELINES.md. Storybook grouping can differ for presentation reasons.

UI Primitives

Základní, znovupoužitelné UI stavební bloky:

| Komponenta | Popis | | --------------------- | ------------------------------------------------------------------------------------------------ | | Avatar | Avatary s podporou obrázků, iniciál a fallbacku | | Badge | Štítky s 12 barevnými variantami, 3 velikostmi, podporou ikon a removable módem | | Button | Tlačítka s variantami (primary, secondary, tertiary, link), destruktivním módem a loading stavem | | ButtonGroup | Seskupení tlačítek s horizontální/vertikální orientací | | Checkbox | Zaškrtávací pole s indeterminate stavem a validací | | Collapsible | Rozbalovací komponenta (Compound Component s Root, Trigger, Content) | | Container | Responzivní kontejner s konfigurovatelnou max-šířkou | | Copyright | Komponenta pro zobrazení copyrightu | | Divider | Horizontální/vertikální oddělovač | | Dropdown | Rozbalovací menu (Compound Component) s klávesovou navigací | | Headline | Nadpisy s různými úrovněmi a styly | | Input / Textarea | Textová pole s podporou prefixů, suffixů, ikon a validace | | NavItem | Základní navigační položka s volitelným submenu triggerem nebo přímým odkazem | | PageItem | Položka stránkování použitelná samostatně nebo jako low-level building block pro Pagination | | RangeSlider | Rozsahový slider pro výběr min-max hodnot | | SearchResultItem | Položka výsledku vyhledávání (použitelná samostatně nebo se Searchbar) | | ShowMoreList | Seznam s rozbalovacím "Zobrazit více" tlačítkem | | SocialLink | Odkaz na sociální síť s ikonou | | Toggle | Přepínač (switch) se dvěma velikostmi a validací | | Tooltip | Tooltip s konfigurovatelnou pozicí pomocí Floating UI |

Patterns

Komplexní komponenty složené z UI primitivů pro specifické business use-cases:

| Komponenta | Popis | | ---------------------- | ----------------------------------------------------------------------------------------- | | Alert | Inline notifikační pattern s tone variantami, popisem a volitelným dismiss tlačítkem | | Breadcrumbs | Navigační breadcrumb pattern s overflow logikou, truncation a collapsing položek | | BlogPostCard | Karta blog článku s obrázkem, kategorií, nadpisem a metadaty (Compound Component) | | CTABanner | Call-to-action banner s titulkem, popisem a tlačítkem | | CurrencySwitcher | Přepínač měn (využívá Dropdown primitive) | | FooterLinks | Sekce odkazů do patičky stránky | | FormField | Form wrapper pattern pro label, helper/error text a ARIA vazby | | HeroBanner | Hero banner s pozadím, nadpisem a CTA tlačítkem | | LanguageSwitcher | Přepínač jazyků (využívá Dropdown primitive) | | ProductCard | Karta produktu s interaktivními částmi (Compound Component: Image, Badge, Actions, atd.) | | Searchbar | Vyhledávací pole s rozbalovacím menu (Compound Component) | | Select | Jednovýběrový dropdown s vyhledáváním, postavený na Dropdown primitive | | Slider | Carousel pattern s viewportem, arrows, dots a slide orchestration postavený na Embla | | MultiSelect | Vícehodnotový dropdown s badge chipy a integrovaným vyhledáváním | | Pagination | Komplexní stránkování s režimy button/link, i18n ready a optional load-more flow | | SubNavigation | Vedlejší navigace postavená na NavItem položkách pro horizontální seznam odkazů | | Tabs | Přístupný tabs pattern s controlled i uncontrolled režimem a keyboard navigací | | Toast | Provider-driven toast notification pattern s viewportem, queue a timed visibility |

🚀 Instalace

# npm
npm install @blueghostcz/e4-component-library

# pnpm (doporučeno)
pnpm add @blueghostcz/e4-component-library

# yarn
yarn add @blueghostcz/e4-component-library

Peer dependencies

Knihovna vyžaduje následující peer dependencies:

{
  "next": "^14.1.0 || ^15.0.0",
  "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0",
  "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"
}

💡 React 19 Ready: Knihovna je primárně navržena pro React 19 a využívá jeho moderní features (ref jako prop, automatické memo). Plně kompatibilní i s React 16-18.

💡 Použití

Základní import

import { Button, Input, Badge } from "@blueghostcz/e4-component-library";

export default function MyComponent() {
  return (
    <div>
      <Badge variant="success" size="sm">
        Nový
      </Badge>
      <Button variant="primary" size="md">
        Klikni na mě
      </Button>
      <Input placeholder="Zadej email..." />
    </div>
  );
}

Tree-shaking optimalizovaný import

Pro lepší tree-shaking můžete importovat komponenty přímo:

import Button from "@blueghostcz/e4-component-library/Button";
import Input from "@blueghostcz/e4-component-library/Input";

🎨 Theming a customizace

Knihovna používá třívrstvou architekturu stylů:

1. Foundations (styles/foundations/) - základní design tokeny (barvy, spacing, typography...)
2. Variables (styles/variables.scss) - komponentové proměnné, které používají foundations
3. Component Modules (*.module.scss) - styly konkrétních komponent, které používají proměnné z variables.scss

Jak funguje přepisování stylů

Každá komponenta má ve svém SCSS modulu proměnné s !default, které odkazují na variables.scss. Konzumující aplikace si zkopíruje celou strukturu stylů (variables.scss + foundations/) a přepíše hodnoty podle potřeby.

Postup pro customizaci

1. Zkopírujte styly z knihovny do svého projektu

# Zkopírujte variables.scss a foundations složku
cp -r node_modules/@blueghostcz/e4-component-library/dist/styles/foundations src/styles/
cp node_modules/@blueghostcz/e4-component-library/dist/styles/variables.scss src/styles/

Struktura ve vašem projektu:

src/styles/
├── foundations/
│   ├── _breakpoints.scss
│   ├── _colors.scss
│   ├── _radius.scss
│   ├── _shadows.scss
│   ├── _spacing.scss
│   ├── _typography.scss
│   └── ...
└── variables.scss

2. Upravte hodnoty podle potřeby

// src/styles/foundations/_colors.scss - přepište barvy
$brand-600: #5e35b1; // Nová brand barva místo výchozí #0282ac
$brand-700: #4527a0;

// src/styles/variables.scss - přepište komponentové proměnné
$btn-border-radius: $radius-md; // Použije váš radius token
$focus-ring-width: 3px; // Širší focus ring
$input-border-color: $gray-300; // Jiná barva rámečku

3. Nakonfigurujte Next.js

// next.config.ts
import path from "node:path";
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  sassOptions: {
    includePaths: [path.join(process.cwd(), "src/styles")],
    prependData: `@use "variables" as *;`,
  },
};

export default nextConfig;

Struktura variables.scss

// 1. Forward & import foundations (barvy, spacing, typography...)
@forward "./foundations/breakpoints";
@forward "./foundations/colors";
// ...
@use "./foundations/_colors" as *;
@use "./foundations/_spacing" as *;
// ...

// 2. Globální systémové proměnné
$focus-ring-width: 2px;
$focus-ring-color: rgba($brand-600, 0.25);

// 3. Komponentové proměnné (používají foundations)
$btn-primary-bg: $brand-700;
$btn-border-radius: $radius-md;
$input-border-color: $gray-300;
// ... stovky dalších proměnných

Všechny komponenty automaticky převezmou vaše vlastní hodnoty.

🛠 Vývoj knihovny

Následující sekce jsou určeny pro vývojáře knihovny, ne pro její konzumenty.

Požadavky

• Node.js 18+
• pnpm (doporučený package manager)

Instalace pro vývoj

git clone [email protected]:blueghostcz/e4-component-library.git
cd e4-component-library
pnpm install

Příkazy

| Příkaz | Popis | | ------------------------ | ----------------------------------------- | | pnpm storybook | Spustí Storybook na http://localhost:6006 | | pnpm build | Buildne knihovnu do dist/ | | pnpm test | Spustí Vitest v watch režimu | | pnpm test:run | Spustí Vitest jednorázově | | pnpm test:ui | Spustí Vitest s UI | | pnpm test:coverage | Generuje coverage report | | pnpm test:visual | Spustí Playwright visual testy | | pnpm test:visual:update| Aktualizuje Playwright snapshoty | | pnpm lint | ESLint kontrola | | pnpm lint:fix | ESLint kontrola s automatickými opravami | | pnpm lint:scss | Stylelint kontrola SCSS | | pnpm lint:scss:fix | Stylelint kontrola SCSS s opravami | | pnpm typecheck | TypeScript kontrola bez buildu | | pnpm build-storybook | Buildne statický Storybook | | pnpm preview-storybook | Preview buildnutého Storybooku | | pnpm icons:generate | Generuje React komponenty z SVG ikon | | pnpm icons:clean | Smaže vygenerované React komponenty ikon |

📁 Struktura projektu

e4-component-library/
├── src/
│   ├── assets/
│   │   └── images/
│   │       └── icons/         # Zdrojové SVG ikony
│   ├── components/
│   │   ├── Icons/             # Automaticky generované React komponenty
│   │   └── ui/                # UI komponenty
...

Workflow pro ikony

Knihovna obsahuje automatizovaný workflow pro převod SVG ikon na React komponenty.

1. Vložte SVG soubory do adresáře src/assets/images/icons.
2. Spusťte generátor příkazem:

   pnpm icons:generate

3. Hotové komponenty se vygenerují v src/components/Icons a automaticky se exportují pro použití v knihovně.

Pro detailní informace o fungování a možnostech skriptů se podívejte do dokumentace v scripts/iconConverter/README.md.

Struktura komponenty

Každá komponenta má následující strukturu:

ComponentName/
├── index.tsx                  # Komponenta + exporty
├── ComponentName.module.scss  # Styly (SCSS Module)
├── ComponentName.stories.tsx  # Storybook stories
└── _test/
    └── ComponentName.test.tsx # Unit testy

🧪 Testování

Používáme vícevrstvou testovací strategii s různými typy testů pro maximální pokrytí.

1. Storybook Play Functions (interaktivní testy)

Testování uživatelských interakcí přímo v prohlížeči.

pnpm storybook    # Testy běží automaticky při zobrazení story

• ✅ Simulace kliknutí, hover, keyboard navigace
• ✅ Accessibility testování (WCAG 2.1 AA)
• ✅ Cross-browser kompatibilita
• ✅ Reálné prostředí prohlížeče

2. Vitest Unit Tests (konfigurační testy)

Validace story konfigurací a TypeScript typů.

pnpm test         # Watch mode
pnpm test:run     # Jednorázové spuštění
pnpm test:ui      # S grafickým UI

• ✅ Validace props a args ve stories
• ✅ Kontrola meta konfigurace
• ✅ TypeScript type safety

3. Snapshot Tests (HTML struktura)

Zachycení HTML struktury komponent pro detekci nechtěných změn.

pnpm test                    # Spustí i snapshot testy
pnpm test -- -u              # Aktualizuje snapshoty

• ✅ Detekce změn v DOM struktuře
• ✅ Rychlé (běží v JSDOM)
• ✅ Textové porovnání (git-friendly)

Soubory: _test/*.snapshot.test.tsx → __snapshots__/*.snap

4. Visual Regression Tests (screenshoty)

Pixel-perfect porovnání screenshotů pomocí Playwright.

pnpm test:visual             # Spustí vizuální testy (vyžaduje běžící Storybook)
pnpm test:visual:update      # Aktualizuje golden screenshoty
pnpm test:visual:ui          # S Playwright UI pro debugging

• ✅ Detekce vizuálních změn (barvy, spacing, layout)
• ✅ Golden screenshoty verzované v gitu
• ✅ Běží lokálně i v CI (zdarma, na rozdíl od Chromatic)

Soubory: e2e/*.visual.test.ts → e2e/*.ts-snapshots/*.png

Přehled testovacích příkazů

| Příkaz | Popis | | ------------------------- | ----------------------------------- | | pnpm test | Unit + snapshot testy (watch mode) | | pnpm test:run | Unit + snapshot testy (jednorázově) | | pnpm test:ui | Unit testy s grafickým UI | | pnpm test:coverage | Coverage report | | pnpm test:visual | Vizuální testy (Playwright) | | pnpm test:visual:update | Aktualizace golden screenshotů |

Struktura testů v komponentě

ComponentName/
├── index.tsx
├── ComponentName.stories.tsx      # Play functions (interaktivní testy)
└── _test/
    ├── ComponentName.test.tsx            # Unit testy (story konfigurace)
    ├── ComponentName.snapshot.test.tsx   # Snapshot testy (HTML struktura)
    └── __snapshots__/
        └── *.snap                        # Uložené HTML snapshoty

e2e/
└── componentname.visual.test.ts    # Vizuální testy (screenshoty)
    └── *.ts-snapshots/
        └── *.png                   # Golden screenshoty

Pro detailní dokumentaci viz TestingGuide.mdx ve Storybooku.

🔧 Tech Stack

| Technologie | Verze | Účel | | ------------------- | ----- | ------------------------------- | | React | 19 | UI framework | | TypeScript | 5 | Type safety | | Storybook | 10 | Dokumentace & testování | | Vitest | 4 | Unit testy | | Playwright | 1.57 | Browser testing | | SCSS Modules | - | Scoped styling | | tsup | 8 | Bundling | | Floating UI | 0.27 | Tooltip/Dropdown positioning | | Embla Carousel | 8.6 | Carousel/Slider funkcionalita | | clsx | 2.1 | Podmíněné CSS třídy |

📖 Dokumentace pro vývojáře

| Dokument | Popis | | ------------------------------------------------------------- | ------------------------------------------------ | | COMPONENT_GUIDELINES.md | ⭐ Principy návrhu kvalitních komponent | | ADDING_NEW_COMPONENT.md | ⭐ Postup přidání nové komponenty | | PAGINATION_SPEC.md | Detailní specifikace Pagination komponenty | | RELEASE_PROCESS.md | Proces vydání nové verze na npm | | LOCAL_TESTING_SETUP.md | Lokální testování s konzumující aplikací | | CHANGELOG.md | Historie změn |

🤝 Přispívání

Workflow pro novou komponentu

1. Vytvoř feature branch: git checkout -b feat/component-name
2. Rozhodni taxonomy podle COMPONENT_GUIDELINES.md a implementuj komponentu ve src/components/ui/ nebo src/components/patterns/
3. Přidej Storybook stories s play functions
4. Přidej unit testy
5. Exportuj komponentu - viz ADDING_NEW_COMPONENT.md
6. Pokud se mění taxonomy nebo source location, aktualizuj i exporty, build wiring, Storybook a docs
7. Spusť testy: pnpm test
8. Vytvoř pull request

Checklist před PR

• [ ] Komponenta má TypeScript interface
• [ ] SCSS modul s !default proměnnými
• [ ] Storybook stories s play functions
• [ ] Unit testy
• [ ] Exporty ve 3 souborech (tsup.config.ts, src/index.ts, package.json)
• [ ] Accessibility (WCAG 2.1 AA)
• [ ] pnpm test prochází
• [ ] pnpm lint prochází

📄 Licence

MIT © BlueGhost.cz

Vytvořeno s ❤️ týmem BlueGhost.cz