guidelines_widgets.md

Гайдлайны по написанию виджетов

Из правил могут быть исключения, но они должны быть документированы рядом с местом их возникновения.

Совместимость с Bootstrap

Виджеты должны использовать Bootstrap-совместимые классы для оформления.

Корневой элемент

Виджет (в частности его корневой элемент) должен вести себя либо как блочный элемент, либо как строковый элемент.

Обычно это достигается простым правилом: на корневом элементе виджета не должно быть CSS свойств position, top/right/bottom/left, width/height, flex/flex-*, margin/margin-*.

Внутреннее состояние

Виджет не должен иметь внутреннего состояния, его состояние должно быть полностью выражаемо значениями его пропов.

События вместо мутации пропов

Когда внутри виджета происходит что-то, что должно поменять его пропы, он должен бросить событие с новым значением. Затем родитель может на свое усмотрение поменять проп, на изменение которого виджет должен отреагировать.

Если виджет отвечает за одно единственное изменяемое значение, тогда это должна быть пара:

• Vue: проп value и событие input. Сокращается до v-model.
• React: пропы value и onChange.

Если виджет отвечает за несколько независимых значений, тогда для каждого значения (на примере photo) должна быть пара:

• Vue: проп photo и событие update:photo. Сокращается до photo.sync (см. sync props).
• React: пропы photo и onChangePhoto.

Vue $slots не использовать в computed, ибо $slots нереактивны. Но можно использовать условную отрисовку слотов, опираясь на вычисление has в $slots в методах, т.к. vue компонент ререндерится каждый раз при изменении родителя, если у него есть хоть 1 слот, задекларированный в родителе.