Исключаемые аргументы Storybook (references/storybook-arg-types.md)

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

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

Когда добавлять

Добавлять аргумент в EXCLUDED_ARG_TYPES, если одновременно выполняются условия:

  • аргумент нужен только для настройки демонстрации в Storybook;
  • аргумент преобразуется внутри story в публичные пропсы, содержимое или поведение примера;
  • потребитель компонента не может и не должен передавать этот аргумент в production-коде.

Не добавлять в EXCLUDED_ARG_TYPES публичные пропсы компонента, даже если они скрыты из Controls по технической причине.

Именование и типизация

  • Называть служебный story-проп с префиксом _, например _showIcon.
  • Описывать его отдельным локальным типом StoryProps и объединять с публичными пропсами только на уровне story.
  • Не добавлять служебный проп в публичный Props компонента и не передавать его через spread в компонент.
type StoryProps = {
  _showIcon: boolean;
};

export const Default: StoryFn<ComponentProps & StoryProps> = ({
  _showIcon,
  ...args
}) => <Component {...args} icon={_showIcon ? <Icon /> : undefined} />;

Регистрация и Controls

Добавлять русское отображаемое имя в EXCLUDED_ARG_TYPES из src/.storybook/constants.ts под ключом компонента:

export const EXCLUDED_ARG_TYPES = {
  Component: {
    _showIcon: "Показать иконку",
  },
};

Использовать это значение в argTypes, не дублируя строку:

argTypes: {
  _showIcon: {
    control: "boolean",
    name: EXCLUDED_ARG_TYPES.Component._showIcon,
  },
},

Публичная таблица пропсов

Служебные story-пропсы могут оставаться доступными в Controls, но не должны отображаться в таблице публичного API компонента.

В docs.mdx импортировать EXCLUDED_ARG_TYPES и исключать отображаемые имена служебных аргументов:

import { EXCLUDED_ARG_TYPES } from "core-ui-storybook/constants";

<ArgTypes exclude={Object.values(EXCLUDED_ARG_TYPES.Component)} />

Использовать Object.values, потому что argTypes.name заменяет техническое имя _showIcon на русское отображаемое имя из EXCLUDED_ARG_TYPES.

Если у истории нет служебных пропсов, не создавать пустую секцию компонента в EXCLUDED_ARG_TYPES и не добавлять исключение в docs.mdx.

Производные сценарии

При создании отдельной истории на основе компонента или его Default-истории проверять унаследованные args, argTypes и parameters.controls. Storybook объединяет параметры истории с meta, поэтому Controls могут показать пропсы, которые новый сценарий фактически не использует.

В argTypes производной истории явно отключать:

  • публичные пропсы компонента, которые зафиксированы внутри примера и не должны управляться из этого сценария;
  • служебные пропсы других историй из EXCLUDED_ARG_TYPES;
  • технические пропсы, уже исключённые на уровне meta.

Не переопределять parameters.controls.exclude производной истории: при объединении с meta это может скрыть Controls у других сценариев. Для ненужных аргументов задавать control: false и table: { disable: true } локально в Story.argTypes. Сверять служебные ключи с EXCLUDED_ARG_TYPES базовой истории.

Тип пропсов производной истории объединять с публичными пропсами компонента, даже если исполняемый example использует только служебный аргумент. Иначе TypeScript не позволит описать унаследованные публичные пропсы в Story.argTypes:

type CustomSkeletonStoryProps = CustomLayerProps & {
  _skeleton: boolean;
};

Оставлять в Controls только аргументы, которые принимает и применяет исполняемый example этой истории. Например, если история демонстрирует собственные скелетоны в children, скрывать унаследованные skeleton, skeletonHeight и служебный проп показа другого swapper:

CustomSkeleton.parameters = {
  docs: {
    source: {
      code: Examples.customSkeletonCode,
    },
  },
};

CustomSkeleton.argTypes = {
  skeleton: {
    control: false,
    table: { disable: true },
  },
  skeletonHeight: {
    control: false,
    table: { disable: true },
  },
  _showHeadingSwapper: {
    control: false,
    table: { disable: true },
  },
  _skeleton: {
    control: "boolean",
    name: EXCLUDED_ARG_TYPES.CustomLayer._skeleton,
  },
};

После создания истории открыть её Controls или проверить собранный Storybook и убедиться, что каждый видимый control реально влияет на этот сценарий. Для статической Common без args отсутствие Controls считать ожидаемым; оно не должно влиять на Controls интерактивных историй.