|
| 1 | +# Керівні принципи проєкту |
| 2 | + |
| 3 | +## 1. Структура проєкту |
| 4 | + |
| 5 | +Проєкт дотримується конкретної структури для забезпечення узгодженості в процесі розробки та супроводу. |
| 6 | +Вихідний код розташований у теці `source`, а скомпільований — у теці `lib`. |
| 7 | + |
| 8 | +## 2. Структура вихідного коду |
| 9 | + |
| 10 | +Вихідний код поділяється на модулі, які розташовані в теках в теці `source`: |
| 11 | +- `colors-css` — модулі, що реалізують кольори |
| 12 | +- `common-css` — модулі, що реалізують загальні стилі |
| 13 | +- `common-js` — модулі, що реалізують загальні функції |
| 14 | +- `components` — модулі, що реалізують компоненти |
| 15 | +- `core` — модулі, що реалізують ядро бібліотеки |
| 16 | +- `datetime` — модуль, що реалізує компоненти для роботи з датою та часом |
| 17 | +- `dom` — модуль, що реалізує компоненти для роботи з DOM |
| 18 | +- `extensions` — модулі, що реалізують розширення стандартних JavaScript об'єктів |
| 19 | +- `farbe` — модуль, що реалізує роботу з кольором |
| 20 | +- `guardian` — модуль, що реалізує функції валідації даних |
| 21 | +- `hooks` — модулі, що реалізують хуки (`useMemo`, `useState`, `useEffect`, тощо) |
| 22 | +- `html` — модулі, що реалізують функції для створення HTML елементів на JavaScript |
| 23 | +- `i18n` — модулі, що реалізують функції для роботи з локалізацією |
| 24 | +- `icons` — модулі, що реалізують функції для роботи з іконками |
| 25 | +- `include` — LESS модулі, що реалізують змінні стилів та міксіни |
| 26 | +- `model` — модуль, що реалізує функції для роботи з реактивною моделлю даних |
| 27 | +- `reset` — модуль, що реалізує скидання стилів |
| 28 | +- `router` — модуль, що реалізує функції для роботи з маршрутизацією для SPA |
| 29 | +- `string` — модуль, що реалізує функції для роботи з рядками |
| 30 | + |
| 31 | +Окремі файли в теці `source`: |
| 32 | +- `index.js` — точка входу для бандлерів, включає в зборку всі компоненти та стилі |
| 33 | +- `i18n.js` — точка входу для бандлерів, включає всі локалізації |
| 34 | +- `icons.js` — точка входу для бандлерів, включає всі іконки |
| 35 | +- `runtime.js` — точка входу для бандлерів, включає в зборку всі функції, які не є компонентами і стилями |
| 36 | +- `default.js` — точка входу для бандлерів, включає в зборку `reset`, `common{css,js}`, `i18n`, `runtime`, and all `component` |
| 37 | + |
| 38 | +### 2.1. Компоненти |
| 39 | +Кожен компонент має свою теку, в якій розташовані файли `index.js`, `[component-name].less`, `[component-name].js`. |
| 40 | +Також, у теці компонента, можуть бути розташовані додаткові включення компонентів, які використовуються поточним компонентом. |
| 41 | + |
| 42 | +### 2.2. Стилі кольору |
| 43 | +Стилі кольору розташовані в теці `colors-css`. Кожен файл являє собою окремий модуль з класами, які реалізують одну специфічну поведінку. |
| 44 | + |
| 45 | +### 2.3. Загальні стилі |
| 46 | +Загальні стилі розташовані в теці `common-css`. Кожен файл являє собою окремий модуль з класами, які реалізують одну специфічну поведінку. |
| 47 | + |
| 48 | +### 2.4. Загальні функції |
| 49 | +Загальні функції розташовані в теці `common-js`. Файл містить різноманітні функції, які не є компонентами або стилями, але використовуються в різних компонентах. |
| 50 | + |
| 51 | +### 2.5. Зовнішні модулі |
| 52 | +В теках: `dom`, `html`, `datetime`, `farbe`, `guardian`, `hooks`, `model`, `router`, та `string` розташовані функції, які підключають сторонні модулі для використання з Metro UI. |
| 53 | + |
| 54 | +### 2.6. Ядро бібліотеки |
| 55 | +В теці `core` розташовані модулі, які реалізують ядро бібліотеки та глобальний неймспейс `Metro`. |
| 56 | + |
| 57 | +## 3. Вимоги до тестування |
| 58 | + |
| 59 | ++ Для тестування вихідного коду використовуються тести на основі фреймворку Latte (@olton/latte). |
| 60 | ++ Документація по тестуванню доступна за посиланням: [Latte Documentation](https://latte.org.ua) |
| 61 | ++ Тестування вихідного коду є обов'язковим для всіх компонентів, які реалізують нову функціональність або змінюють існуючу. |
| 62 | ++ Тестування вихідного коду є необов'язковим для компонентів, які реалізують лише стилі або не змінюють функціональність. |
| 63 | ++ Запуск тестів можна здійснити за допомогою команди |
| 64 | +```bash |
| 65 | +npm test |
| 66 | +``` |
| 67 | ++ Для мокінгу використовуються функції фреймворку Latte: `mock()`, `spy()` |
| 68 | ++ Для створення тестових груп використовуються функції фреймворку Latte: `suite()` або `describe()`. Ці функції не можуть бути вкоаденими в інші функції. |
| 69 | ++ Для створення тестів всередині групи використовується функція фреймворку Latte: `it()`. |
| 70 | ++ Для створення окремо стоячих тестів використовується функція фреймворку Latte: `test()`. |
| 71 | + |
| 72 | +## 4. Code Style |
| 73 | + |
| 74 | ++ Для форматування вихідного коду використовується `Biom`. |
| 75 | ++ Форматування має відповідати вимогам [JavaScript Standard Style](https://standardjs.com/) за виключенням того, що замість 2-х пробілів, використовується 4 пробіли. |
| 76 | + |
| 77 | +## 5. Documentation |
| 78 | +This guide provides instructions for creating documentation for Metro UI components. |
| 79 | +The documentation should be in markdown format and placed in a README.md file in each component's directory. |
| 80 | +The documentation should describe plugin parameters, API methods (excluding those starting with an underscore), and how to style the component using CSS variables. |
| 81 | + |
| 82 | +Документація складається з файлів `README.md`, які розташовані в теках компонентів. |
| 83 | +Якщо є відповідний приклад використання компонента в теці `__html__`, то його слід використовувати як приклад використання компонента. |
| 84 | +Майже всі компоненти ініціалізуються за допомогою `data-role` атрибута, тому в прикладах використання слід використовувати `data-role` атрибут. |
| 85 | + |
| 86 | +Винятком є компоненти: |
| 87 | +- `notify` |
| 88 | +- `toast` |
| 89 | +- компоненти які реалізуються лише в стилях (у таких компонентах відсутній файл `[component-name].js`) |
| 90 | + |
| 91 | +Для деяких компонентів реалізовані додаткові методи ініціалізації, зазвичай для таких компонентів створюється окремий неймспейс в об'єкті `Metro` (наприклад: `Metro.notify`, `Metro.toast`). |
| 92 | + |
| 93 | +Readme.md кожного компонента повинен дотримуватися цієї структури: |
| 94 | + |
| 95 | +### Documentation Structure |
| 96 | + |
| 97 | +#### 5.1. **Title and Description** |
| 98 | + ```markdown |
| 99 | + # Component Name |
| 100 | + |
| 101 | + Brief description of what the component does and its main features. |
| 102 | + ``` |
| 103 | + |
| 104 | +#### 5.2. **Usage Examples** |
| 105 | + ```markdown |
| 106 | + ## Usage |
| 107 | + |
| 108 | + ### Basic Usage |
| 109 | + |
| 110 | + ```html |
| 111 | + <!-- Example HTML code --> |
| 112 | + <div data-role="component-name"></div> |
| 113 | + ``` |
| 114 | + |
| 115 | + ### Additional Configurations |
| 116 | + |
| 117 | + ```html |
| 118 | + <!-- More examples showing different configurations --> |
| 119 | + ``` |
| 120 | + |
| 121 | +#### 5.3. **Plugin Parameters** |
| 122 | + ```markdown |
| 123 | + ## Plugin Parameters |
| 124 | + |
| 125 | + | Parameter | Type | Default | Description | |
| 126 | + | --------- | ---- | ------- | ----------- | |
| 127 | + | `paramName` | type | default | Description of parameter | |
| 128 | + ``` |
| 129 | + |
| 130 | +#### 5.4. **API Methods** |
| 131 | + ```markdown |
| 132 | + ## API Methods |
| 133 | + |
| 134 | + ### Method Name |
| 135 | + |
| 136 | + ```javascript |
| 137 | + // Example of method usage |
| 138 | + $('#element').data('component-name').methodName(); |
| 139 | + ``` |
| 140 | + |
| 141 | +#### 5.5. **Events** |
| 142 | + ```markdown |
| 143 | + ## Events |
| 144 | + |
| 145 | + | Event | Description | |
| 146 | + | ----- | ----------- | |
| 147 | + | `onEventName` | Description of event | |
| 148 | + ``` |
| 149 | + |
| 150 | +#### 5.6. **CSS Variables** |
| 151 | + ```markdown |
| 152 | + ## Styling with CSS Variables |
| 153 | + |
| 154 | + | Variable | Default (Light) | Dark Mode | Description | |
| 155 | + | -------- | --------------- | --------- | ----------- | |
| 156 | + | `--variable-name` | value | value | Description of variable | |
| 157 | + |
| 158 | + ### Example of Custom Styling |
| 159 | + |
| 160 | + ```css |
| 161 | + /* Custom styling example */ |
| 162 | + #my-element { |
| 163 | + --variable-name: custom-value; |
| 164 | + } |
| 165 | + ``` |
| 166 | + |
| 167 | +#### 5.7. **CSS Classes** |
| 168 | + ```markdown |
| 169 | + ## Available CSS Classes |
| 170 | + |
| 171 | + ### Base Classes |
| 172 | + - `.class-name` - Description |
| 173 | + |
| 174 | + ### Modifiers |
| 175 | + - `.modifier-class` - Description |
| 176 | + ``` |
| 177 | + |
| 178 | +### How to Create Documentation |
| 179 | + |
| 180 | +For each component that needs documentation: |
| 181 | + |
| 182 | +1. **Examine the Component Files**: |
| 183 | + - Look at the JavaScript file (e.g., `component-name.js`) to understand: |
| 184 | + - Default configuration options (usually in a variable like `ComponentDefaultConfig`) |
| 185 | + - API methods (public methods that don't start with underscore or `#`) |
| 186 | + - Events (usually in the configuration with names like `onEvent`) |
| 187 | + |
| 188 | + - Look at the LESS file (e.g., `component-name.less`) to understand: |
| 189 | + - CSS variables (usually defined in `:root` and `.dark-side` selectors) |
| 190 | + - Available CSS classes and their purpose |
| 191 | + |
| 192 | +2. **Create the README.md File**: |
| 193 | + - Use the structure outlined above |
| 194 | + - Include practical examples showing different configurations |
| 195 | + - Document all parameters, methods, events, and styling options |
| 196 | + - Provide clear descriptions for each item |
| 197 | + |
| 198 | +3. **Test the Documentation**: |
| 199 | + - Ensure all examples are correct and work as expected |
| 200 | + - Verify that all parameters, methods, and CSS variables are accurately documented |
0 commit comments