Проброшенные свойства вложенных компонентов (references/exposed-props.md)

Источник: ds-skills/core-ui-development-skills/src/skills/build-core-ui-components/references/exposed-props.md — справочник скилла build-core-ui-components

В контракте дизайна это поле exposed у узла: true — кандидат в публичный API, false — наружу не выносить.

Вложенный компонент в макете может быть помечен как проброшенный: его свойства видны в панели у того, кто вставил родителя. Это заявленная дизайном часть публичного API родителя, а не деталь реализации.

Где брать список

Машинный блок «Контракт» в карточке компонента: узлы с exposed: true, подмена вложенного компонента — поле swapFrom, слоты — раздел slots.
Если блока в карточке нет, запросить список у автора макета: в Figma это флаг isExposedInstance у прямых инстансов.
Не выводить список из внешнего вида макета и не считать проброшенным всё, что на нём видно.

Перенос в публичный API


`exposed: true`, два и более свойства	объект-проп `backButton?: Pick<IconButtonProps, "appearance" \| "disabled">`	вложенный компонент один и не подменяется
`exposed: true`, одно свойство	плоский проп по роли элемента	отдельный объект не оправдан
`swapFrom`, `slots`	`ReactNode`-проп	потребитель подставляет собственный узел
проброса нет	ничего	свойство остаётся внутренним

Типизировать объект-проп через Pick от пропсов вложенного компонента, а не его полным типом: иначе родитель теряет контроль над остальными свойствами.
Называть проп по роли элемента (backButton, actions), а не по имени слоя в макете.
Не принимать снаружи свойство, которым родитель управляет сам. Если размер вложенной кнопки следует из размера родителя, не выносить его даже при проброшенном инстансе.
Не добавлять проброшенное свойство, которое не нужно текущей задаче.

type NavigationBarProps = {
  /** Настройки кнопки возврата. Кнопка скрыта, если проп не передан. */
  backButton?: Pick<IconButtonProps, "appearance" | "disabled" | "onClick">;
};

Проброс — сигнал, а не разрешение

Проброс сообщает намерение: это потребитель вправе настраивать. Обратное утверждение сильнее — не проброшенное свойство в публичный API не выносить, оно описывает состояние самого компонента.

Если проброшенное свойство нарушает инвариант родителя, не выносить его и классифицировать расхождение как LIMITATION по границам изменений. Сообщить, какое свойство проброшено в макете и по какой причине не вынесено.

Storybook

Описывать объект-пропсы в argTypes с control: "object", чтобы сценарий настраивался из панели.
Не заменять публичный проброшенный проп служебным story-пропсом: правила служебных аргументов — в исключаемых аргументах.