Правила именования

Haunted — это библиотека для создания веб-компонентов с использованием функционального подхода, построенного на хуках, аналогичных React. Правильное именование компонентов и связанных сущностей имеет критическое значение для читаемости кода, масштабируемости проекта и интеграции с другими библиотеками.

Имена компонентов

Компоненты в Haunted всегда определяются как функции. Имя функции должно начинаться с заглавной буквы. Это позволяет отличать пользовательские компоненты от обычных HTML-элементов и поддерживает стандартное поведение веб-компонентов. Например:

import { html, component } from 'haunted';

function UserCard({ name, age }) {
  return html`<div>${name}, ${age} лет</div>`;
}

customElements.define('user-card', component(UserCard));
  • Функция-компонент: UserCard
  • HTML-тег компонента: user-card

Рекомендации:

  • Использовать CamelCase для имен функций-компонентов.
  • Для HTML-тегов применять kebab-case.
  • Имена должны быть осмысленными, отражать содержимое или роль компонента.

Атрибуты и свойства

Haunted автоматически связывает атрибуты HTML с пропсами компонента, но это связывание чувствительно к регистру и формату имен.

  • Атрибуты в HTML: kebab-case
  • Свойства в Jav * aScript: camelCase

Пример корректного связывания:

function ProfileCard({ userName, userAge }) {
  return html`<p>${userName} — ${userAge} лет</p>`;
}

customElements.define('profile-card', component(ProfileCard));

HTML:

<profile-card user-name="Иван" user-age="30"></profile-card>

Важно: user-name автоматически преобразуется в проп userName.

Хуки и вспомогательные функции

Haunted предоставляет набор хуков: useState, useEffect, useReducer, и другие. Имена хуков начинаются с use и пишутся в camelCase:

import { useState } from 'haunted';

function Counter() {
  const [count, setCount] = useState(0);

  return html`<button @click=${() => setCount(count + 1)}>Счёт: ${count}</button>`;
}

customElements.define('counter-button', component(Counter));
  • Все локальные переменные и функции внутри компонента должны иметь осмысленные имена, отражающие их назначение.
  • Функции-обработчики событий часто именуются с префиксом handle, например: handleClick, handleSubmit.

События

Именование событий в Haunted и веб-компонентах должно соответствовать общепринятой практике:

  • Пользовательские события: kebab-case, часто с префиксом компонента для избежания конфликтов.
  • Обработчики: on<Event>, например, onClick, onChange.

Пример:

this.dispatchEvent(new CustomEvent('profile-updated', {
  detail: { name: 'Иван' },
  bubbles: true,
  composed: true
}));

В компоненте-потребителе:

<profile-card @profile-updated=${handleProfileUpdate}></profile-card>

Константы и состояния

Состояния, создаваемые через useState или useReducer, именуются так, чтобы отражать тип и цель хранения данных:

const [todos, setTodos] = useState([]);
const [isLoading, setIsLoading] = useState(false);
  • Префикс is или has для булевых переменных.
  • Множественное число для массивов.
  • set + название состояния для функций обновления.

Константы вне компонента обычно пишутся в SCREAMING_SNAKE_CASE:

const API_URL = 'https://example.com/api';

Имена слотов и шаблонов

Если компонент использует слоты, их имена должны быть короткими, осмысленными и в kebab-case:

<modal-dialog>
  <span slot="header">Заголовок</span>
  <p slot="body">Содержимое модального окна</p>
</modal-dialog>

Сводка ключевых правил

  1. Компоненты: функция в CamelCase, тег в kebab-case.
  2. Пропсы: camelCase в JS, kebab-case в HTML.
  3. Хуки: начинаются с use, camelCase.
  4. События: кастомные события в kebab-case, обработчики on<Event>.
  5. Состояния: set + имя состояния, булевы с is/has, массивы во множественном числе.
  6. Константы: SCREAMING_SNAKE_CASE.
  7. Слоты: короткие, осмысленные, kebab-case.

Эти правила обеспечивают единообразие кода, упрощают поддержку и интеграцию компонентов в большие проекты.

Оглавление