Kurs JavaScript i React · Moduł 15: Wzorce i architektura

Projekt końcowy - Architektura kosmicznej stacji

7 min czytania ·
W tej lekcji5

Znasz już kilkanaście wzorców, ale każdy ćwiczyłeś osobno, jak moduły sprawdzane pojedynczo w hangarze. Stacja orbitalna działa dopiero wtedy, gdy moduły są połączone. Czas na podsumowanie wszystkiego, czego nauczyliśmy się w tym module! Twoim zadaniem jest zaprojektowanie i zbudowanie Mission Control Dashboard, czyli panelu kontroli misji kosmicznej, z wykorzystaniem wszystkich poznanych wzorców.

Wymagania projektu

Twój projekt powinien wykorzystywać:

  1. Composition: wieloslotowy layout (header, sidebar, main)
  2. Container/Presentational: separacja logiki od UI
  3. Custom hooks: wyodrębniona logika (np. useMission, useCrewFilter)
  4. Compound Components: system zakładek lub accordion
  5. Atomic Design: organizacja komponentów w atomy, molekuły, organizmy

W projekcie dla mentora dojdą co najmniej trzy własne hooki: useToggle, useFetch i useFilter.

Architektura projektu

Zanim napiszesz pierwszą linijkę, rozplanuj foldery. Poniższa struktura układa komponenty według poziomów Atomic Design, a logikę trzyma osobno w hookach:

MissionDashboard/
  atoms/
    StatusBadge     - wyświetla status misji (active/completed/failed)
    ProgressBar     - pasek postępu misji
    IconButton      - przycisk z ikoną
  molecules/
    MissionCard     - karta misji (StatusBadge + tytuł + ProgressBar)
    CrewMember      - członek załogi (avatar + imię + rola)
  organisms/
    MissionList     - lista misji z filtrowaniem
    CrewPanel       - panel załogi z wyszukiwaniem
    Tabs/Tab/Panel  - compound component z zakładkami
  hooks/
    useMission      - logika zarządzania misjami
    useFilter       - logika filtrowania
    useToggle       - przełącznik stanów

Atomy nie znają danych, molekuły łączą atomy, a dopiero organizmy sięgają po hooki. Jeśli atom importuje hook z danymi, coś poszło nie tak. React nie narzuca struktury folderów: w większych aplikacjach kod często grupuje się według funkcji (features/missions, features/crew), a Atomic Design zostawia dla wspólnej biblioteki komponentów.

Kluczowe wzorce w projekcie

Custom Hook - useMission

Sercem panelu jest hook, który trzyma listę misji i aktualny filtr, a na zewnątrz oddaje przefiltrowane dane oraz akcję zmiany statusu:

function useMission() {
  const [missions, setMissions] = useState(initialMissions);
  const [filter, setFilter] = useState('all');

  const filteredMissions = useMemo(() => {
    if (filter === 'all') return missions;
    return missions.filter(m => m.status === filter);
  }, [missions, filter]);

  const updateStatus = (id, status) => {
    setMissions(prev =>
      prev.map(m => m.id === id ? { ...m, status } : m)
    );
  };

  return { missions: filteredMissions, filter, setFilter, updateStatus };
}

useMemo liczy listę na nowo tylko wtedy, gdy zmienią się misje albo filtr. updateStatus tworzy nową tablicę przez map i nie modyfikuje oryginału. W zadaniu praktycznym ten hook nazywa się useMissionData, ale logika jest ta sama.

Compound Components - Tabs

Compound components to rodzina komponentów, które działają razem i dzielą ukryty stan, jak <select> i <option> w HTML. Tak wygląda użycie zakładek w panelu:

function MissionControl() {
  return (
    <Tabs defaultTab={0}>
      <Tabs.TabList>
        <Tabs.Tab index={0}>Misje</Tabs.Tab>
        <Tabs.Tab index={1}>Załoga</Tabs.Tab>
        <Tabs.Tab index={2}>Systemy</Tabs.Tab>
      </Tabs.TabList>

      <Tabs.Panel index={0}>
        <MissionList />
      </Tabs.Panel>
      <Tabs.Panel index={1}>
        <CrewPanel />
      </Tabs.Panel>
      <Tabs.Panel index={2}>
        <SystemsOverview />
      </Tabs.Panel>
    </Tabs>
  );
}

Tabs.Tab i Tabs.Panel nie dostają aktywnej zakładki przez propsy, tylko czytają ją ze wspólnego kontekstu, który tworzy Tabs. Szkielet takiego zestawu jest krótki:

const TabsContext = createContext(null);

function Tabs({ defaultTab = 0, children }) {
  const [activeTab, setActiveTab] = useState(defaultTab);
  return (
    <TabsContext.Provider value={{ activeTab, setActiveTab }}>
      {children}
    </TabsContext.Provider>
  );
}

Tabs.Tab = function Tab({ index, children }) {
  const { activeTab, setActiveTab } = useContext(TabsContext);
  return (
    <button role="tab" aria-selected={activeTab === index} onClick={() => setActiveTab(index)}>
      {children}
    </button>
  );
};

Atrybut aria-selected działa tylko razem z rolą tab: dzięki nim czytnik ekranu wie, że to zakładka i która jest aktywna. Tabs.TabList to kontener z rolą tablist, a Tabs.Panel renderuje dzieci z rolą tabpanel tylko wtedy, gdy activeTab === index. MissionControl się nie zmienia, bo kontekst to szczegół wewnętrzny zestawu. Tak zbudowane są też zakładki w Radix UI, które dodatkowo łączą zakładkę z panelem atrybutem aria-controls.

Composition - Dashboard Layout

Całość spina układ z trzema slotami, znany z pierwszej lekcji modułu. Nagłówek, panel boczny i główna część dostają gotowe elementy od App:

function DashboardLayout({ header, sidebar, children }) {
  return (
    <div className="dashboard">
      <header className="dash-header">{header}</header>
      <div className="dash-body">
        <aside className="dash-sidebar">{sidebar}</aside>
        <main className="dash-content">{children}</main>
      </div>
    </div>
  );
}

function App() {
  return (
    <DashboardLayout
      header={<TopBar title="Panel kontroli misji" />}
      sidebar={<StatusPanel />}
    >
      <MissionControl />
    </DashboardLayout>
  );
}

DashboardLayout nie wie nic o misjach ani zakładkach, więc ten sam układ posłuży też dla panelu załogi.

Wskazówki implementacyjne

Krok 1: Custom hooks

Zacznij od wyodrębnienia logiki do custom hooków. Każdy hook powinien mieć jedną odpowiedzialność, jak ten przełącznik:

// useToggle - prosty przełącznik stanów
function useToggle(initial = false) {
  const [value, setValue] = useState(initial);
  const toggle = useCallback(() => setValue(v => !v), []);
  return [value, toggle];
}

useToggle zwraca parę jak useState, a useCallback sprawia, że toggle jest tą samą funkcją między renderami. Drugi hook filtruje dowolną listę według wpisanego tekstu:

// useFilter - logika filtrowania (bez debounce)
function useFilter(items, filterFn) {
  const [query, setQuery] = useState('');

  const filteredItems = useMemo(() => {
    if (!query) return items;
    return items.filter(item => filterFn(item, query));
  }, [items, query, filterFn]);

  return { filteredItems, query, setQuery };
}

Ten hook nie ma debounce: filtruje przy każdym znaku, co przy kilkudziesięciu misjach wystarczy. Przy długich listach pomoże wbudowany useDeferredValue, dzięki któremu pisanie pozostaje płynne. filterFn zdefiniuj poza komponentem, bo nowa funkcja przy każdym renderze unieważnia useMemo. Trzeci hook, useFetch(url), napiszesz jak useCrew z lekcji o Container/Presentational: stan data, loading i error oraz useEffect z pobieraniem.

Krok 2: Atomy i molekuły

Zbuduj proste, wielokrotnego użytku komponenty. Atom nie wie nic o misjach, zna tylko status, który ma pokazać, i mapę statusLabels z etykietami dla załogi:

// Atom - StatusBadge
const statusLabels = { active: 'Aktywna', completed: 'Ukończona', failed: 'Nieudana' };

function StatusBadge({ status }) {
  const colors = {
    active: '#00e676',
    completed: '#64b5f6',
    failed: '#f44336',
  };
  return (
    <span style={{ background: colors[status], padding: '4px 12px', borderRadius: '20px' }}>
      {statusLabels[status]}
    </span>
  );
}

Wartości statusów zostają w kodzie po angielsku, bo porównuje je logika, a załoga widzi polskie etykiety. Molekuła łączy atomy w coś, co ma już znaczenie: kartę konkretnej misji z nazwą, statusem i paskiem postępu:

// Molekuła - MissionCard (łączy atomy)
function MissionCard({ mission, onStatusChange }) {
  return (
    <div className="mission-card">
      <h3>{mission.name}</h3>
      <StatusBadge status={mission.status} />
      <ProgressBar value={mission.progress} />
    </div>
  );
}

MissionCard przyjmuje onStatusChange, ale jeszcze go nie używa. Podepniesz go w projekcie, na przykład do przycisku, który oznacza misję jako ukończoną. ProgressBar to drugi atom, który znasz już z lekcji o Atomic Design.

Krok 3: Organizmy z danymi

Połącz molekuły w większe struktury. Organizm jako pierwszy sięga po hook z danymi i rozdaje je kartom:

// MissionList - organizm z filtrowaniem
function MissionList() {
  const { missions, filter, setFilter, updateStatus } = useMission();

  return (
    <div>
      <FilterBar value={filter} onChange={setFilter} />
      {missions.map(m => (
        <MissionCard key={m.id} mission={m} onStatusChange={updateStatus} />
      ))}
    </div>
  );
}

MissionList pełni tu rolę komponentu kontenerowego: bierze dane z useMission i przekazuje je w dół. FilterBar to kolejna molekuła do napisania.

Krok 4: Złóż w template

Na końcu połącz wszystko w layout z kompozycją. W Atomic Design ten poziom to template: DashboardLayout ze slotami, do których wkładasz organizmy. Wypełniony prawdziwymi danymi staje się stroną (page), piątym i ostatnim poziomem.

Kryteria oceny

  1. Composition: layout z przynajmniej 3 slotami (header, sidebar, main)
  2. Container/Presentational: separacja logiki od widoku w co najmniej 2 komponentach
  3. Custom hooks: minimum 3 własne hooki z reużywalną logiką (useToggle, useFetch, useFilter)
  4. Compound Components: system zakładek lub accordion ze współdzielonym stanem
  5. Atomic Design: widoczna organizacja w atomy, molekuły, organizmy

Moja rada: buduj od dołu i uruchamiaj aplikację po każdym kroku. Najpierw hooki z danymi wypisanymi w konsoli, potem atomy, a na końcu cały panel. Powodzenia, pilocie! Pokaż, że potrafisz projektować architekturę React jak prawdziwy inżynier kosmiczny.

Pamiętaj: stacja orbitalna to nie jeden wielki moduł, tylko wiele małych, dobrze połączonych.

Kod do tej lekcji: App.jsx
import React, { createContext, useContext, useState, useCallback, useMemo } from 'react';

// =============================================
// CUSTOM HOOKI
// =============================================
function useToggle(initial = false) {
  const [value, setValue] = useState(initial);
  const toggle = useCallback(() => setValue(p => !p), []);
  return [value, toggle];
}

function useMission() {
  const [missions, setMissions] = useState([
    { id: 1, name: 'Eksploracja Alfa Centauri', status: 'active', progress: 65 },
    { id: 2, name: 'Wydobycie w pasie asteroid', status: 'active', progress: 30 },
    { id: 3, name: 'Ratowanie zespołu Bravo', status: 'completed', progress: 100 },
    { id: 4, name: 'Skan głębokiego kosmosu', status: 'failed', progress: 12 },
    { id: 5, name: 'Zaopatrzenie stacji', status: 'active', progress: 80 },
  ]);
  const [filter, setFilter] = useState('all');

  const filteredMissions = useMemo(() => {
    if (filter === 'all') return missions;
    return missions.filter(m => m.status === filter);
  }, [missions, filter]);

  const updateStatus = useCallback((id, status) => {
    setMissions(prev => prev.map(m =>
      m.id === id ? { ...m, status, progress: status === 'completed' ? 100 : m.progress } : m
    ));
  }, []);

  return { missions: filteredMissions, allMissions: missions, filter, setFilter, updateStatus };
}

// =============================================
// KOMPONENT ZŁOŻONY (COMPOUND COMPONENT): Tabs
// =============================================
const TabsCtx = createContext();

function Tabs({ children, defaultTab = 0 }) {
  const [active, setActive] = useState(defaultTab);
  return (
    <TabsCtx.Provider value={{ active, setActive }}>
      <div className="tabs">{children}</div>
    </TabsCtx.Provider>
  );
}
Tabs.TabList = function TabList({ children }) {
  return <div className="tab-list" role="tablist">{children}</div>;
};
Tabs.Tab = function Tab({ index, children }) {
  const { active, setActive } = useContext(TabsCtx);
  const selected = active === index;
  return (
    <button role="tab" aria-selected={selected} className={`tab ${selected ? 'active' : ''}`} onClick={() => setActive(index)}>
      {children}
    </button>
  );
};
Tabs.Panel = function TabPanel({ index, children }) {
  const { active } = useContext(TabsCtx);
  return active === index ? <div className="tab-panel" role="tabpanel">{children}</div> : null;
};

// =============================================
// ATOMY
// =============================================
// Wartości statusów zostają w kodzie, załoga widzi polskie etykiety
const statusLabels = { active: 'Aktywna', completed: 'Ukończona', failed: 'Nieudana' };
const filterLabels = { all: 'Wszystkie', active: 'Aktywne', completed: 'Ukończone', failed: 'Nieudane' };

function StatusBadge({ status }) {
  const colors = { active: 'green', completed: 'blue', failed: 'red' };
  return <span className={`badge badge-${colors[status] || 'gray'}`}>{statusLabels[status] || status}</span>;
}

function ProgressBar({ value, label }) {
  const color = value >= 80 ? '#4caf50' : value >= 40 ? '#ff9800' : '#f44336';
  return (
    <div className="progress-bar" role="progressbar" aria-label={label} aria-valuenow={value} aria-valuemin={0} aria-valuemax={100}>
      <div className="progress-fill" style={{ width: `${value}%`, background: color }} />
    </div>
  );
}

// =============================================
// MOLEKUŁY
// =============================================
function MissionCard({ mission, onComplete, onCancel }) {
  return (
    <div className="mission-card">
      <div className="mc-header">
        <h4>{mission.name}</h4>
        <StatusBadge status={mission.status} />
      </div>
      <ProgressBar value={mission.progress} label={mission.name} />
      {mission.status === 'active' && (
        <div className="mc-actions">
          <button className="btn-sm btn-success" onClick={() => onComplete(mission.id)}>
            Ukończ
          </button>
          <button className="btn-sm btn-danger" onClick={() => onCancel(mission.id)}>
            Anuluj
          </button>
        </div>
      )}
    </div>
  );
}

function CrewMember({ name, role }) {
  return (
    <div className="crew-member">
      <div className="cm-avatar">{name[0]}</div>
      <div>
        <div className="cm-name">{name}</div>
        <div className="cm-role">{role}</div>
      </div>
    </div>
  );
}

// =============================================
// ORGANIZMY
// =============================================
function MissionList({ missions, onComplete, onCancel }) {
  return (
    <div className="mission-list">
      {missions.length === 0 && <p className="empty-msg">Żadna misja nie pasuje do filtra</p>}
      {missions.map(m => (
        <MissionCard key={m.id} mission={m} onComplete={onComplete} onCancel={onCancel} />
      ))}
    </div>
  );
}

function CrewPanel() {
  const crew = [
    { name: 'Komandor Nova', role: 'Kapitan' },
    { name: 'Dr Stellar', role: 'Oficer medyczny' },
    { name: 'Astro', role: 'Inżynier' },
    { name: 'Ra', role: 'Nawigator' },
  ];
  return (
    <div className="crew-panel">
      {crew.map(c => <CrewMember key={c.name} name={c.name} role={c.role} />)}
    </div>
  );
}

function SystemsOverview() {
  const systems = [
    { name: 'Silniki', value: 95 },
    { name: 'Osłony', value: 72 },
    { name: 'Podtrzymanie życia', value: 100 },
    { name: 'Komunikacja', value: 88 },
  ];
  return (
    <div className="systems-overview">
      {systems.map(s => (
        <div key={s.name} className="sys-row">
          <span>{s.name}</span>
          <ProgressBar value={s.value} label={s.name} />
          <span className="sys-pct">{s.value}%</span>
        </div>
      ))}
    </div>
  );
}

// =============================================
// TEMPLATE (kompozycja)
// =============================================
function DashboardLayout({ header, sidebar, children }) {
  return (
    <div className="dashboard-layout">
      <header className="dl-header">{header}</header>
      <div className="dl-body">
        {sidebar && <aside className="dl-sidebar">{sidebar}</aside>}
        <main className="dl-main">{children}</main>
      </div>
    </div>
  );
}

// =============================================
// PAGE (strona)
// =============================================
export default function App() {
  const { missions, allMissions, filter, setFilter, updateStatus } = useMission();
  const [showFilters, toggleFilters] = useToggle(true);

  const filters = ['all', 'active', 'completed', 'failed'];

  // Statystyki liczymy z pełnej listy, żeby filtr nie zmieniał sum w nagłówku
  const stats = useMemo(() => ({
    total: allMissions.length,
    active: allMissions.filter(m => m.status === 'active').length,
    done: allMissions.filter(m => m.status === 'completed').length,
  }), [allMissions]);

  return (
    <DashboardLayout
      header={
        <div className="header-bar">
          <h1>Panel kontroli misji</h1>
          <div className="header-stats">
            <span>Razem: {stats.total}</span>
            <span>Aktywne: {stats.active}</span>
            <span>Ukończone: {stats.done}</span>
            <button className="toggle-btn" onClick={toggleFilters}>
              {showFilters ? 'Ukryj filtry' : 'Pokaż filtry'}
            </button>
          </div>
        </div>
      }
      sidebar={showFilters && (
        <div>
          <h3 className="sidebar-title">Filtr misji</h3>
          <div className="filter-group">
            {filters.map(f => (
              <button
                key={f}
                className={`filter-btn ${filter === f ? 'active' : ''}`}
                aria-pressed={filter === f}
                onClick={() => setFilter(f)}
              >
                {filterLabels[f]}
              </button>
            ))}
          </div>
        </div>
      )}
    >
      <Tabs defaultTab={0}>
        <Tabs.TabList>
          <Tabs.Tab index={0}>Misje</Tabs.Tab>
          <Tabs.Tab index={1}>Załoga</Tabs.Tab>
          <Tabs.Tab index={2}>Systemy</Tabs.Tab>
        </Tabs.TabList>
        <Tabs.Panel index={0}>
          <MissionList
            missions={missions}
            onComplete={(id) => updateStatus(id, 'completed')}
            onCancel={(id) => updateStatus(id, 'failed')}
          />
        </Tabs.Panel>
        <Tabs.Panel index={1}>
          <CrewPanel />
        </Tabs.Panel>
        <Tabs.Panel index={2}>
          <SystemsOverview />
        </Tabs.Panel>
      </Tabs>
    </DashboardLayout>
  );
}

Hasła z dokumentacji w tej lekcji

Widzisz błąd w tej lekcji?

Zadania praktyczne w grze

  • Edytor kodu

    Połącz wzorce z modułu w jednym panelu. Hook useMissionData: ___BLANK1___ to lista misji o statusie równym filtrowi (gdy filtr to 'all', hook zwraca wszystkie misje). Hook useToggle: ___BLANK2___ to funkcja aktualizująca, która odwraca poprzednią wartość (toggle jest w useCallback z pustą tablicą, więc nie może czytać value z pierwszego renderu). Compound component Tabs: ___BLANK3___ to obiekt z activeTab i setActiveTab, który Tabs podaje przez TabsContext, a ___BLANK4___ ustawia aria-selected na true tylko dla aktywnej zakładki. Atomy, molekuła, organizm i DashboardLayout ze slotami są gotowe.

  1. Zadanie z kodemPraktyka: projekt końcowy, panel kontroli misji
  2. Projekt do wysłaniaProjekt do mentora: architektura React w panelu kontroli misji
  3. WideoPodsumowanie modułu

Przydatne artykuły