Readme

Toto je hlavný repozitár pre orangesk/eshop. Obsahuje HTML prototypy jednotlivých častí eshopu.

HTML prototypy sú rozčlenené do projektov. Každý projekt má svojho autora (dodávateľ), product ownera (zadávateľ) a resources - odkazy na design files, readme, asana projekt...

Obsah

• Build files
• NPM balik
• Ako prispievať?
• Štruktúra repozitára
• Názov projektu
• Priečinok data / Dátové mockupy
• Priečinok layouts
• Priečinok pages
• Priečinok scripts
• Priečinok styles
• Priečinok utils

Build files

• ODS.css - ODS štýly
• ODS.js - ODS javascript moduly a ich inicializácia
• project.js - projektove JS moduly a ich inicializácia
• project.css - projektové štýly

NPM balik

Každý release je publikovaný na NPM ako balík @orangesk/eshop-assets.

Balík obsahuje build/lib subory a sprite.svg. Nakoľko je to verejný balík, neobsahuje HTML prototypy.

Ako prispievať?

Nakoľko v repozitári spolupracujú viaceré strany, musíme dodržiavať stanovené pravidlá. Orange design system už definuje pravidlá kvality kódu, pre tento repozitár ale platí nasledovný release proces:

• Code review vykonáva spravovateľ repozitára.
• Prispievateľ vždy vytvára pull requesty do dev vetvy podľa branching modelu.
• Po schválení príspevkov a mergnutí do dev vetvy prispievateľ pripraví release vetvu podľa semver pravidiel, vyplní changelog a vytvorí pull request na vydanie novej verzie.

Štruktúra repozitára

orange-web
└── src
    ├── assets # staticke assety, pri builde sa kopiruju do build foldra
    ├── components # vsetky komponenty
    ├── layouts # globalne layouty
    │   └── base.njk # Hlavny layout s megamenu a footrom
    ├── lib
    │   ├── ODS.js # entry point pre ODS scripty
    │   ├── ODS.scss # entry point pre ODS styly
    │   ├── project.js # entry point pre projektove scripty
    │   └── project.scss # entry point pre projektove styly
    ├── pages
    │   ├── index.mdx # homepage tohto repozitara
    │   ├── readme.mdx # stranka tejto dokumentacie
    │   ├── changelog.mdx # stranka changelogu projektu
    │   └── project-name # priecinok pre projekt
    │       └── page-name.mdx # konkrétny prototyp projektu
    ├── scripts
    │   └── megamenu.js # JS pre megamenu
    ├── styles # globalne styly
    │   ├── fonts.scss # stranka changelogu projektu
    │   ├── megamenu.scss # styly pre megamenu
    │   ├── footer.scss # styly pre footer
    │   └── shame.scss # hanba, hacky
    └── utils # utility potrebne na beh tohto repozitara a zdielane pomocne subory k modulom/komponentom

src/components

React komponenty používané na webe Orange.sk. Obsahuje custom komponenty, ktoré ešte neexistujú v ODS (kandidáti) a opakujúce sa patterny.

orange-web/src/components
└── ComponentName # vzdy camel case
    ├── ComponentName.js # komponent samotny
    ├── ComponentName*Partial*.js # pripadny interny komponent
    ├── ComponentName.static.js # JS plugin
    ├── data.js # data zobrazovane komponentom 
    └── styles
        ├── config.scss # scss mapy definuju jednotlive varianty komponentu
        ├── mixins.scss # mixiny generuju styly
        └── config.scss # mixiny vypluvaju styly do konkretnych classnames

Názov projektu

Nový projekt by mal mať vždy názov typu project-name, vzdy lower case, oddeleny pomlckami.

Priečinok data / Dátové mockupy

V obrazovkách prototypov sa často prepoužívajú dáta. Snažme sa vyhýbať vkladaniu konkrétnych dátových štruktúr priamo do obrazovky alebo priamo do komponentu, ktorý využíva tieto dáta.

Dáta používané na viacerých miestach

src/data slúži na vytváranie potrebných štruktúr, ak sme si istý, že tieto dáta bude využívať viac komponentov/stránok.

src/data
└── file-name.js # vzdy lowercase, oddelene pomlckami

Dáta používané len v jednom komponente

Componnet/data.js slúži na vytváranie potrebných štruktúr ktoré konzumuje práve jeden komponent.

src/components/Component
└── data.js

Priečinok layouts

Layouts sú hlavné obaľovače kontentu stránky v priečinku pages.

layouts/
└── base.njk
    ...

Priečinok pages

Všetky prototypy stránok rozdelené po projektoch.

Každá stránka by mala mať názov, ktorý čo najpresnejšie popisuje čo sa na stránke nachádza. Ak je viac podobných stránok rozlišujeme ich príponou na konci názvu stránky.

pages/
└── project-name
    ├── info.json # informácie o projekte. povinný súbor.
    ├── readme.mdx # voliteľné doplňujúce informácie o projekte, napríklad popis správania alebo flowu.
    ├── page-name.mdx # konkrétna stránka
    └── page-name-variant.mdx # variant stránky
├── index.mdx # homepage tohto repozitára. zobrazuje projekty a doplňujúce informácie z info.json
└── readme.mdx # toto readme
    ...

Priečinok scripts

Obsahuje projektové javascriptové moduly. Návod ako vytvoriť modul a používať ho

scripts/
  lib/ # pomocné metódy
  modules/ # JS moduly ktoré sa neviažu na konktrétny komponent
  index.js # webpack entry point pre všetok JS
  main.js # inicializácia JS modulov potrebných pre beh všetkého v tomto repozitári. súbor je oddelený od index.js kôli rozdeleniu build-u.

Priečinok styles

Štýly ktoré nepatria ku konrétnym komponentom.

styles/
  shame.scss # Hanba hanbatá sem patrí všetko čo by sa nemalo robiť, ale treba to urobiť. Napríklad rýchly bugfix.

Priečinok utils

Obsahuje menšie pomocné scripty používané pri vytváraní prototypov.

Neptaria sem utility pre JS ktorý beží v prehliadači.

utils/
  classes.js
  helpers.js
  propTypes.js
  ...