Skip to content

Latest commit

 

History

History
113 lines (87 loc) · 7.93 KB

CONTRIBUTING.md

File metadata and controls

113 lines (87 loc) · 7.93 KB

Разработка

В проекте используется yarn workspaces.

Ознакомиться можно по ссылке Workspaces | Yarn.

Быстрый старт

  1. Склонировать репозиторий и перейти в созданную директорию.
  2. Включить corepack: corepack enable
  3. Установить зависимости: yarn install.
  4. Поднять локально документацию с лайврелоадом: yarn docs:styleguide. Свойства и методы компонента в режиме разработки по умолчанию не генерируются; если они вам нужны, используйте команду yarn docs:styleguide:props.

Документация будет доступна на http://localhost:6060. В ней ведётся вся разработка. Для удобства можно сразу перейти на страницу разрабатываемого компонента (http://localhost:6060/#/UsersStack)

Дополнительные настройки по желанию

Добавить файл .git-blame-ignore-revs в свой git-конфиг:

git config blame.ignoreRevsFile .git-blame-ignore-revs

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

Чеклист для компонента

Организационные моменты

  • Один PR — одна фича/багфикс (рефакторинги выносим в отдельный PR)
  • Дизайн компонента описан в Figma
  • Компонент находится в своей папке в src/components и не делит её с другими публичными компонентами (один файл — один компонент)
  • У компонента есть понятная документация, описанная в директории компонента в файле Readme.md. Файл подключается в styleguide/config.js
  • Вся документация и предупреждения в коде компонента (warnOnce) написаны на русском языке

Требования к разработке

  • В проекте используется CSS Modules (примеры можно увидить ниже).

    ⚠️ Composition

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

  • CSS-классы должны быть в формате camelCase: elementNameModification. Гайд по написанию стилей

  • Свойства className и style навешиваются на корневой элемент компонента

  • Свойства, не используемые в коде компонента, навешиваются на главный элемент компонента. По умолчанию главным является корневой элемент:

    const Component = (props) => <div {...props} className={styles.Component} />;

    Бывают случаи, например, поле ввода, когда главным является именно input, а не обёртка:

    import styles from './Input.module.css';

const Input = ({ mode, style, className, ...restProps }) => {
  return (
    <div
      className={classNames(className, styles.host, mode === 'default' && styles.modeDefault)}
      style={style}
    >
      <input {...restProps} />
    </div>
  );
};

  • Компонент корректно отрисовывается, если не передавать никаких свойств. Вместо defaultProps, deprecated для функциональных компонентов, используем спред:

    import styles from './Component.module.css';

const Component = ({ mode = 'default', className, ...restProps }) => (
  <div
    className={classNames(className, styles.host, mode === 'default' && styles.modeDefault)}
    {...restProps}
  />
);

  • Для цветов, скруглений, размеров, отступов и теней используются css-переменные из vkui-tokens

  • Для типографии используются компоненты Typography там, где это возможно

  • Добавлен export компонента и его свойств в packages/vkui/src/index.ts

  • При описании свойств для тестирования (data-testid) следует придерживаться следующего соглашения:

    • Шаблон JSDoc комментария: "Передает атрибут data-testid для <кого>"
    • Пример: 
      type AlertProps = {
  /**
   * Передает атрибут `data-testid` для кнопки закрытия
   */
  dismissButtonTestId?: string;
};

  • Компонент покрыт юнит- и скриншотными тестами. Гайд по тестированию

  • Компонент корректно отображается на всех платформах, размерах и цветовых схемах. В styleguide для всех этих параметров есть переключатели

  • Код корректно работает на поддерживаемых нами браузерах

  • Для поддержки адаптивности следует придерживаться гайда по написанию адаптивных компонентов

  • a11y (см. пример хорошего PR с внедрением доступности, на который можно равняться #3337):

    • Компонент соответствует требованиям a11y

    • Написаны юнит-тесты на кейсы связанные с a11y

    • В документации компонента есть раздел про a11y (если необходимо)

    • Анимации, которые могут вызвать утомляемость у людей с нарушением вестибулярного аппарата, учитывают запрос @media (prefers-reduced-motion: reduce). Зачастую это анимации появления/исчезновения. В них передвижения, по типу transform: translate(), и/или изменения размера, по типу transform: scale(), должны быть приведены к анимации через прозрачность, например, как сделано в Alert. Есть исключение, когда пользователь сам изменяет объект, например, swipe-back в компоненте View, или анимация совсем незначительная, например, как в Switch или в <Cell mode="removable" /> (в iOS).

      В PR #6979 можно посмотреть больше примеров таких упрощений.