Паспорт компонента экранной формы

На экранной форме приложения на базе Атомкод можно использовать только компоненты, описания которых соответствуют определенной спецификации, называемой паспортом компонента. Паспорт компонента описывает свойства и определяет доступные обработчики событий, а также содержит дополнительную информацию, например, словесное описание компонента, ссылку на макет компонента, список допустимых дочерних компонентов. Паспорт компонента описывается с использованием синтаксиса TypeScript в файле с расширением ts.

Следующий блок демонстрирует структуру паспорта компонента.

// Основной интерфейс паспорта компонента
export interface IControl {
// Метод получения дочерних компонентов.
  GetChildControls?: (Control: any, Metadata: any) => any[];
  
  // Признак принудительной отрисовки актуального состояния дерева компонентов родительского компонента.
  ForceUpdate?: boolean;
  // Уникальный идентификатор компонента для передачи в инфраструктурный сервис пользовательского интерфейса (CMSService).
  ControlType: string;
  // Уникальный идентификатор компонента, в качестве которого принято использовать название компонента.
  ControlId: string;
  // Подробное описание компонента.
  Description: string;
  // Краткое описание компонента.
  ShortDescription?: string;
  // Путь к файлу значка компонента .../controls/static/ControlsIcons/icons.
  Icons?: {
    Icon16?: string;
    Icon48?: string;
  };
  // Ссылка на макет компонента в figma.
  UI: string;
  // Пример вызова компонента в файле *.mdcontainer.
  Sample: string;
  // Описание допустимых дочерних компонентов.
  // Если компонент не имеет дочерних компонентов, указывается пустой массив.
  // Если компонент в качестве дочерних может иметь любые компоненты, указываются имена компонентов или символ "*".
  ChildControls: Array<string>;
  // Признак допустимости записи компонента в виде <Control />:
  // true - DevTools разрешает запись <Control />;
  // false - DevTools требует запись <Control></Control>.
  SelfClosing: boolean;
  // Признак подстановки тега автозакрытия <Control /> по умолчанию: 
  // true - DevTools автоматически предлагает запись <Control />;
  // false - DevTools автоматически предлагает запись <Control></Control>.
  SelfClosingPrefered: boolean;
  // Признак отображения компонента в разделе "Компоненты" Редактора Форм DevTools.
  Hidden?: boolean;
  // Свойства компонента.
  Properties: {
    [propName: string]: IProperty;
  };
  // Пример компонента.
  Examples: IExample;
  // Описание изменений компонента при переходе на новые версии Атомкод.
  MigrationSteps: string;
  // Устаревшее поле, не используется в текущей версии.
  GetPropertiesMetadata?: any;
  // Информация для Release Notes.
  Info?: string;
  // Блок кода компонента, который автоматически добавляется в файл *.mdcontainer при добавлении компонента на экранную форму в визуальном режиме Редактора Форм.
  DevTools?: object;
  // Признак новизны компонента.
  IsNew?: boolean;
}
// Вспомогательный интерфейс
interface IExample {
  // Пример скрипта с применением компонента.
  Script?: string;
  // Описание состояний компонента.
  States: string;
  // Значение или пример использования компонента.
  Value: string;
  // Координаты компонента при добавлении на экранную форму.
  Coordinates?: string;
}
// Вспомогательный интерфейс
interface PosValue {
  // Значение перечисления.
  Value: string;
  // Описание перечисления.
  Description: string;
}
// Вспомогательный интерфейс
interface IProperty {
  // Обязательность свойства. Может принимать значения: 
  // CONTRACTS.Optional для описания необязательного свойства;
  // CONTRACTS.Required для описания обязательного свойства.
  Contract: string;
  // Описание свойства.
  Description: string;
  // Тип значения свойства, например, ValueTypes.Boolean.
  ValueType: string;
  // Значение свойства по умолчанию, которое используется в режиме разработки в DevTools.
  DevValue: any;
  // Значение свойства по умолчанию, которое используется при запуске приложения.
  DefaultValue: any;
  // Тип свойства.
  Type: string;
  // Допустимые значения для свойства-перечисления.
  PosValues?: PosValue[];
  // Массив свойств компонента, на которые влияет изменение значения этого свойства.
  Impact?: string[];
}

Следующий блок демонстрирует пример паспорта компонента Button.

import CONTRACTS from '../../../constants/CONTRACTS';
import commonProperties from '../../../core/Control/commonProperties';
import ValueTypes from '../../../constants/ValueTypes';
import PropertyTypes from '../../../constants/PropertyTypes';
import { IControl } from '../../types';

import icons from '../../static/ControlsIcons';

const IButton: IControl = {
  ControlType: 'Button',
  ControlId: 'Button',
  ShortDescription: 'Отображает кнопку',
  Icons: {
    Icon16: icons.button16,
    Icon48: icons.button48,
  },
  Description: `

Согласно дизайн-системе Атомкод и в зависимости от выполняемой функции имеет несколько режимов работы  
и вариантов стилизации.

Следующие режимы определяют действия, выполняемые по нажатию кнопки:

- Button: происходят только действия, описываемые в обработчике события.
- Reset: введенные на странице данные очищаются, и страница перезагружается.
- Submit: данные, введенные на странице, отправляются на сервер, и страница перезагружается.


~~~jsx
  <Button
    Text="Primary" 
    Style="Primary" 
  />
~~~
`,
  UI: 'https://www.figma.com/design/wMSSQurkeAlLC5ap8w92j8/Components-[Web]?node-id=2517-431502&t=OEb5H6JiPQwt1D26-0',
  Sample: `
    <Button Text="foo" OnClick={() => {}} />
  `,
  ChildControls: ['Icon', "Text", "Group"],
  SelfClosing: true,
  SelfClosingPrefered: true,
  Properties: {
    ...commonProperties,
    FullWidth: {
      Contract: CONTRACTS.Optional,
      Description: 'Признак автоматически назначаемой ширины кнопки согласно ширине родительского компонента.',
      ValueType: ValueTypes.Boolean,
      DevValue: false,
      DefaultValue: false,
      Type: PropertyTypes.Value,
    },
    Text: {
      Contract: CONTRACTS.Optional,
      Description: 'Надпись на кнопке.',
      ValueType: ValueTypes.String,
      DevValue: 'Button',
      DefaultValue: '',
      Type: PropertyTypes.Value,
    },
    OnClick: {
      Contract: CONTRACTS.Optional,
    Description: `
Обработчик события нажатия левой кнопки мыши, когда указатель мыши находится на компоненте.

В качестве параметра принимает объект типа [объект события компонента экранной формы](https://docs.atomkod.ru/Руководство-пользователя/Разработка-приложения-в-DevTools/Разработка-интерфейса-приложения/Разработка-в-кодовом-режиме/Объект-события) 
с дополнительными полями типа [MouseEvent](https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent).

Пример: 
~~~jsx
OnClick={() => {
  // Получение параметра события
  const event = getEvent();
  // Вывод параметра события в консоль браузера
  console.log(event);
  }
}  
~~~
`,
      Type: PropertyTypes.Event,
      ValueType: ValueTypes.Undefined,
      DevValue: '() => ()',
      DefaultValue: null,
    },
    Disabled: {
      Contract: CONTRACTS.Optional,
      Description: 'Признак состояния компонента Отключен.',
      ValueType: ValueTypes.Boolean,
      Type: PropertyTypes.Value,
      DevValue: false,
      DefaultValue: false,
    },
    Mode: {
      Contract: CONTRACTS.Optional,
      ValueType: ValueTypes.Enum,
      Description: 'Режим работы кнопки.',
      Type: PropertyTypes.Value,
      PosValues: [
        {
          Value: 'Button',
          Description: 'По нажатию кнопки происходят только действия, описываемые в обработчике события.',
        },
        {
          Value: 'Reset',
          Description:
            'По нажатию кнопки введенные на странице данные очищаются, и страница перезагружается.',
        },
        {
          Value: 'Submit',
          Description: 'По нажатию кнопки данные, введенные на странице, отправляются на сервер, и страница перезагружается.',
        },
      ],
      DevValue: 'Button',
      DefaultValue: 'Button',
    },
    Style: {
      Contract: CONTRACTS.Optional,
      ValueType: ValueTypes.Enum,
      Description: 'Стиль кнопки согласно дизайн-системе Атомкод.',
      Type: PropertyTypes.Value,
      PosValues: [
        {
          Value: 'Primary',
          Description: `
Используется для кнопки, выполняющей основное, ожидаемое, наиболее вероятное действие, например, "Сохранить", "Добавить", "Применить". На экранной форме приложения обычно используется единожды.`,
        },
        {
          Value: 'Secondary',
          Description: `
Используется при наличии нескольких равновероятных или равнозначных действий. На экранной форме приложения может использоваться более одного раза.`,
        },
        {
          Value: 'PrimaryGray',
          Description: `
Используется для кнопки, выполняющей основное, ожидаемое, наиболее вероятное действие, например, "Сохранить", "Добавить", "Применить". На экранной форме приложения обычно используется единожды.`,
        },
        {
          Value: 'Tertiary',
          Description: `
Используется для кнопки, выполняющей дополнительное, менее приоритетное действие, чем действие, выполняемое по кнопке со стилем Primary, например, "Отменить".`,
        },
        {
          Value: 'PrimaryError',
          Description: `
Используется для кнопки, выполняющей наиболее ожидаемое, приоритетное деструктивное действие на экранной форме приложения, например, "Удалить".`,
        },
        {
          Value: 'SecondaryError',
          Description: `
Используется при наличии нескольких равновероятных или равнозначных деструктивных действий. На экранной форме приложения может использоваться более одного раза.`,
        },
        {
          Value: 'TertiaryError',
          Description: `
Используется для кнопки, выполняющей деструктивное действие. Может использоваться вместо стиля Secondary Red.`,
        },
        {
          Value: 'SecondaryGray',
          Description: `
Используется по умолчанию при наличии нескольких действий с равным приоритетом, например, для кнопок на панели инструментов.`,
        },
        {
          Value: 'TertiaryGray',
          Description: `
Используется вместо стиля Secondary Gray. Например, стиль TertiaryGray может использоваться для кнопки "Отменить", расположенной рядом с кнопкой в стиле Primary.`,
        },
      ],
      DevValue: 'Primary',
      DefaultValue: 'Primary',
    },
  },
  DevTools: {
    DefaultCode: '<Button Text="Button"/>',
  },
  Examples: {
    States: '',
    Value: `<Group Mode="Column" Height="150px">
  <Group Mode="Row">
    <Group Mode="Column" Height="auto" Width="33%">
      <Text Value="Text" Mode="Medium_14" CSS={['ml-8']} />
      <Button
        CSS={['m-8']} 
        Text="Сохранить" 
        Style="Primary"
      />
    </Group>
    
 
</Group>
    `,
  },
  MigrationSteps: `
    Убраны Style: OutlinedPrimary, OutlinedSecondary, Plain
    Добавлены Style: Tertiary, PrimaryError, SecondaryError, TertiaryError, SecondaryGray, TertiaryGray
  `,
};

export default IButton;