Создание компонентов

<div class="redblue-toggle" role="button" aria-pressed="false">
  Переключить <span class="redblue-toggle__color">синий</span>
</div>

class RedblueTogglePrototype {
  get toggled() {
    return this.root.getAttribute('aria-pressed') === 'true';
  }

  set toggled(toggled) {
    this.toggle(toggled);
  }

  constructor(root) {
    this.root = root;
    this.clickHandler = () => this.toggle();
    this.initialize();
  }

  initialize() {
    this.root.addEventListener('click', this.clickHandler);
  }

  destroy() {
    this.root.removeEventListener('click', this.clickHandler);
  }
}
```  toggle(isToggled = undefined) {
    const wasToggledExplicitlySet = isToggled === Boolean(isToggled);
    const toggled = wasToggledExplicitlySet ? isToggled : !this.toggled;
    const toggleColorEl = this.root.querySelector<HTMLElement>('.redblue-toggle__color');
    let toggleColor;

    this.root.setAttribute('aria-pressed', String(toggled));
    if (toggled) {
      toggleColor = 'Красный';
      this.root.classList.add('redblue-toggle--toggled');
    } else {
      toggleColor = 'Синий';
      this.root.classList.remove('redblue-toggle--toggled');
    }
    toggleColorEl.textContent = toggleColor;
  }
}

new RedblueTogglePrototype(document.querySelector<HTMLElement>('.redblue-toggle'));

class RedblueTogglePrototype {
  get toggled() {
    return SOMEHOW_GET_ATTRIBUTE('aria-pressed') === 'true';
  }

  set toggled(toggled) {
    this.toggle(toggled);
  }

  constructor(root) {
    this.root = root;
    this.clickHandler = () => this.toggle();
    this.initialize();
  }

  initialize() {
    this.root.addEventListener('click', this.clickHandler);
  }

  destroy() {
    this.root.removeEventListener('click', this.clickHandler);
  }

  toggle(isToggled = undefined) {
    const wasToggledExplicitlySet = isToggled === Boolean(isToggled);
    const toggled = wasToggledExplicitlySet ? isToggled : !this.toggled;

    let toggleColor;

    SOMEHOW_SET_ATTRIBUTE('aria-pressed', String(toggled));
    if (toggled) {
      toggleColor = 'Red';
      SOMEHOW_ADD_CLASS('redblue-toggle--toggled');
    } else {
      toggleColor = 'Blue';
      SOMEHOW_REMOVE_CLASS('redblue-toggle--toggled');
    }
    SOMEHOW_UPDATE_TOGGLE_COLOR_TEXT_CONTENT(toggleColor);
  }
}
```В приведенном выше коде все взаимодействия с окружением хоста заменены на фейковые методы `SOMEHOW_*`. Теперь можно преобразовать эти фейковые методы в интерфейс адаптера.

| Поддельная сигнатура метода | Сигнатура адаптерного метода |
| --- | --- |
| SOMEHOW_GET_ATTRIBUTE(attr: string) => string | getAttr(attr: string) => string |
| SOMEHOW_SET_ATTRIBUTE(attr: string, value: string) | setAttr(attr: string, value: string) |
| SOMEHOW_ADD_CLASS(className: string) | addClass(className: string) |
| SOMEHOW_REMOVE_CLASS(className: string) | removeClass(className: string) |
| SOMEHOW_UPDATE_TOGGLE_COLOR_TEXT_CONTENT(textContent: string) | setToggleColorTextContent(textContent: string) |

Примечание: Мы больше не рекомендуем использовать `registerInteractionHandler` и `deregisterInteractionHandler` как адаптерные методы для добавления/удаления общих обработчиков событий. Обработка событий значительно различается между фреймворками (например, [React Synthetic Events](https://reactjs.org/docs/events.html)), поэтому мы рекомендуем управлять событиями на уровне компонентов.### Переработка вашего существующего кода в основной класс

Теперь, когда наш API адаптера определен, наш существующий код может быть переработан в основной класс.
Как правило, в нашем коде, мы определяем статический геттер `defaultAdapter`, который возвращает
адаптер сNOP сигнатурами для каждого метода. Это помогает нам проверять форму адаптера,
предотвращать ошибки адаптеров, когда методы забываются, и в будущем (и это должно быть сделано)
использовать для построения инструментов для проверки правильной формы адаптера. Этот пример показывает это,
а также использует наш класс `MDCFoundation`, который является базовым классом, от которого наследуются все основные классы.

```ts
class RedblueToggleFoundation extends MDCFoundation {
  static get defaultAdapter() {
    return {
      getAttr: (attr: string) => '',
      setAttr: (attr: string, value: string) => undefined,
      addClass: (className: string) => undefined,
      removeClass: (className: string) => undefined,
      setToggleColorTextContent: (textContent: string) => undefined,
      registerInteractionHandler: (type: string, handler: EventListener) => undefined,
      deregisterInteractionHandler: (type: string, handler: EventListener) => undefined,
    };
  }

  private toggled = false;

  constructor(adapter) {
    super({...RedblueToggleFoundation.defaultAdapter, ...adapter});
  }

  handleClick() {
    this.toggle();
  }

  isToggled() {
    return this.adapter.getAttr('aria-pressed') === 'true';
  }

  private toggle(isToggled = undefined) {
    const wasToggledExplicitlySet = isToggled === Boolean(isToggled);
    this.toggled = wasToggledExplicitlySet ? isToggled : !this.toggled;

    let toggleColor;
  }
``````markdown
Обратите внимание на использование `isToggled()` и `toggle()` вместо сеттеров и геттеров. Учитывая, что основа представляет собой более низкоуровневый API, мы считаем, что данная конвенция уместна.

this.adapter.setAttr('aria-pressed', String(this.toggled));
if (this.toggled) {
  toggleColor = 'Красный';
  this.adapter.addClass('redblue-toggle--toggled');
} else {
  toggleColor = 'Синий';
  this.adapter.removeClass('redblue-toggle--toggled');
}
this.adapter.setToggleColorTextContent(toggleColor);
}
```### Создайте компонент на основе этой основы, предоставив адаптер

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

* Предоставление идиоматического интерфейса к функциональности основы в контексте хостовой среды
* Предоставление адаптера к основе, который позволит ей работать в контексте хостовой среды

Так как этот компонент является простым компонентом, он должен быть спроектирован в соответствии с простым API DOM, которое предпочитает использование геттеров и сеттеров для реализации своей функциональности (например, `checked`, `disabled` и т.д.). Наш адаптер крайне прост, так как мы можем просто переиспользовать методы, с которых начали.

```ts
class RedblueToggle extends MDCComponent {
  initialize() {
    this.listen('click', this.foundation.handleClick);
  }

  destroy() {
    this.unlisten('click', this.foundation.handleClick);
  }

  get toggled() {
    return this.foundation.isToggled();
  }

  set toggled(toggled) {
    this.foundation.toggle(toggled);
  }

  getDefaultFoundation() {
    return new RedblueToggleFoundation({
      getAttr: attr => this.root.getAttribute(attr),
      setAttr: (attr, value) => this.root.setAttribute(attr, value),
      addClass: className => this.root.classList.add(className),
      removeClass: className => this.root.classList.remove(className),
      setToggleColorTextContent: textContent => {
        this.root.querySelector<HTMLElement>('.redblue-toggle__color').textContent = textContent;
      },
    });
  }
}

packages/
  ├── mdc-component/
      ├── test/
          ├── foundation.test.ts # Единичные тесты для основы компонента
          ├── mdc-component.test.ts # Единичные тесты для компонента
      ├── README.md # Инструкции по использованию и документация API
      ├── adapter.ts # Интерфейс адаптера, реализуемый обёртками фреймворков и чистым компонентом
      ├── foundation.ts # Бизнес-логика, независимая от фреймворка, используемая обёртками фреймворков и чистым компонентом
      ├── component.ts # Чистый компонент и реализации адаптера для клиентов, не использующих фреймворк
      ├── constants.ts # Константные значения, используемые одним или несколькими файлами в пакете (например, cssClasses, strings, numbers)
      ├── index.ts # Перенаправляет экспорт из других файлов в пакете (adapter, foundation, component, util и т.д.)
      ├── types.ts # (необязательно) Содержит типы и интерфейсы, выведенные в публичные API, не связанные с чистым компонентом
      ├── util.ts # (необязательно) Помощники, независимые от фреймворка (например, обнаружение функций)
      ├── mdc-component.scss # Основной файл исходного кода CSS для компонента
      └── package.json # Файл пакета компонента

"publishConfig": {
  "access": "public"
}

"keywords": [
  "material components",
  "material design",
  <COMPONENT_NAME>
]

{
  "name": "@material/example",
  "version": "0.0.0",
  "description": "Компонент Material Components для веба example",
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/material-components/material-components-web.git"
  },
  "keywords": [
    "material components",
    "material design",
    "example"
  ],
  "publishConfig": {
    "access": "public"
  }
}

Copyright <ГОД> Google Inc.
```Данное разрешение предоставляется бесплатно любому лицу, получившему копию
этого программного обеспечения и связанных с ним документационных файлов («Программное обеспечение»), для использования
Программного обеспечения без каких-либо ограничений, включая, но не ограничиваясь правами
на использование, копирование, изменение, объединение, публикацию, распространение, предоставление sublicenses и/или продажу
копий Программного обеспечения, а также для предоставления лицам, которым предоставляется Программное обеспечение, права на то, чтобы
делать то же самое, при условии соблюдения следующих условий:The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. ПОДКЛЮЧЕНИЕ ПОДКЛЮЧЕНО "КАК ЕСТЬ", БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ, ЯВНЫХ ИЛИ ПОДРАЗУМЕВАЕМЫХ, ВКЛЮЧАЯ, НО НЕ ОГРАНИЧИВАЯСЯ, ГАРАНТИЯМИ ТОРГОВЛЕНИЯ, ПРИГОДНОСТИ ДЛЯ КОНКРЕТНЫХ ЦЕЛЕЙ И НЕНАРУШЕНИЯ. В НИКАКОМ СЛУЧАЕ АВТОРЫ И ДОЛЖНИКИ ПРАВА КОПИРОВАНИЯ НЕ НЕСУТ ОТВЕТСТВЕННОСТИ ЗА КАКИЕ-ЛИБО ПРЕТЕНЗИИ, УЩЕРБЫ ИЛИ ДРУГИЕ ОТВЕТСТВЕННОСТИ, В ТОМ ЧИСЛЕ В СВЯЗИ С ДЕЙСТВИЕМ ДОГОВОРА, ДЕЛИКТОМ ИЛИ ИНЫМ, ВОЗНИКШИМ ИЗ, В СВЯЗИ С ИЛИ В СВЯЗИ С ПОДКЛЮЧЕНИЕМ ПОДКЛЮЧЕНИЯ ИЛИ ИСПОЛЬЗОВАНИЕМ ИЛИ ДРУГИМИ СВЯЗЯМИ С ПОДКЛЮЧЕНИЕМ ПОДКЛЮЧЕНИЯ.

```Пожалуйста, добавьте этот комментарий в начало каждого исходного файла, заменив `<YEAR>` на год создания файла.

### SCSS

#### Отдельно выделяйте переиспользуемые переменные и миксины из основного SCSS

Если переменные и миксины предназначены для использования вне одного стилейшета, перенесите их
в [частичные файлы SASS](http://sass-lang.com/guide#topic-4). Эти файлы затем могут быть включены
в другие стилейшеты без повторного опускания лишнего CSS. В качестве правила, никогда не `@import`
файлы SASS, которые выводят CSS, так как это, скорее всего, будет дублированным выводом.

#### Следуйте модифицированному паттерну BEM

Мы следуем модифицированному варианту [паттерна BEM](http://getbem.com/), который определен в наших
[правилах stylelint](../.stylelintrc.yaml#L252-L255). Это, в основном:```scss
.mdc-block {

}

.mdc-block__element {

}

.mdc-block--modifier {

}

.mdc-block {
  // ...

  &__element {
    // ...
  }
}

.mdc-block--modifier {
  // ...

  .mdc-block__element {
    // ...
  }
}

// stylelint-disable plugin/selector-bem-pattern

// стили, которые вызывают жалобы по селекторам BEM...

// stylelint-enable plugin/selector-bem-pattern

class MDCNewComponent extends MDCComponent {
  static attachTo(root) {
    return new MDCNewComponent(root);
  }
}
````mdc-auto-init` требует присутствия этого метода, и мы гарантируем его предоставление для удобства наших пользователей. Мы говорили о написании правила для линтера для этого в будущем.

#### Определите getter для defaultAdapter для каждого фундамента
Все фундаменты **должны** определить статический метод `defaultAdapter`, который возвращает адаптер со всеми определёнными функциями. Функции должны быть, по сути, NOPs; принимать никаких параметров и возвращать правильный тип (например, `false` для булева типа, `0` для числа, `{}` для объекта и т.д.). Наша конвенция состоит в том, чтобы аннотировать функцию с помощью встроенных комментариев с использованием [типовых аннотаций TypeScript](https://basarat.gitbooks.io/typescript/content/docs/types/type-system.html).Также принято переопределять конструктор фундамента для смешивания переданного параметра `adapter` с объектом по умолчанию. Это гарантирует, что адаптер имеет правильную форму.

```js
class MDCNewComponentFoundation extends MDCFoundation {
  static get defaultAdapter() {
    return {
      addClass: (/* className: string */) => {},
      getAttr: (/* attr: string */) => /* string */ '',
      // ...
    }
  }

  constructor(adapter) {
    super(...MDCNewComponentFoundation.defaultAdapter, ...adapter);
  }
}

```javascript
export const numbers = {
  DEFAULT_THROTTLE_DELAY_MS: 300,
};
```

// foundation.ts

```javascript
import {cssClasses, strings, numbers} from './constants';

class MDCNewComponentFoundation extends MDCFoundation {
  static get defaultAdapter() {
    // ...
  }

  static get cssClasses() {
    return cssClasses;
  }

  static get strings() {
    return strings;
  }

  static get numbers() {
    return numbers;
  }
}
```

Основная цель этого — чтобы наши компоненты могли взаимодействовать с аспектами инфраструктуры фронтенда Google, такими как механизм [переименования CSS-классов](https://github.com/google/closure-stylesheets#renaming) в Closure Stylesheets. Кроме того, это обеспечивает дополнительную выгоду в виде семантического кода и меньшего количества магических строк и чисел.

#### Расширение компонентов и оснований от классов mdc-base.
Чтобы гарантировать последовательное поведение всех пакетов, все компоненты должны наследоваться от `MDCComponent`, а все основания — от `MDCFoundation`. Дополнительная информация о обоих этих классах доступна в [README mdc-base](../packages/mdc-base).

#### Пакеты должны быть зарегистрированы с нашей системой сборки и с пакетом material-components-web
Каждый раз, когда вы создаете новый компонент, важно уведомить соответствующие инструменты и пакеты о нем. Конкретно:
```- Убедитесь, что для него существует запись в `webpack.config.js` для модулей `js-components` и `css`.
- Убедитесь, что он добавлен как зависимость `material-components-web`. Если компонент содержит стили, убедитесь, что они импортированы с помощью `@import` в `material-components-web.scss`. Если компонент содержит JavaScript, убедитесь, что его пространство имен компонента экспортировано в `material-components-web`, и что он зарегистрирован с `mdc-auto-init`. Наконец, не забудьте добавить его в `package.json` пакета `material-components-web`.
- Убедитесь, что правильный **предмет коммита** для пакета добавлен в массив `config.validate-commit-msg.scope.allowed` в `package.json` на верхнем уровне репозитория. Предмет коммита — это _имя компонента без префикса `mdc-`/`@material/`_. Например, для `mdc-icon-button` правильный предмет — `icon-button`.#### Совместимость с TypeScript
```Все основные компоненты MDC Web должны быть полностью совместимы с режимом строгого соответствия [TypeScript](https://www.typescriptlang.org/). Мы предоставили список требований и дальнейшее объяснение соответствия TypeScript, а также конвенции, примеры и распространенные паттерны TypeScript, с которыми вы можете не быть знакомы, в нашем [Руководстве по лучшим практикам программирования](./code/best_practices.md).```

### Проверка

Следующие руководства следует использовать для написания тестов для кода MDC Web. Наши тесты написаны с использованием [Jasmine](https://jasmine.github.io/) и запускаются с помощью [Karma](https://karma-runner.github.io/1.0/index.html).

#### Проверка адаптеров основ
При тестировании основ, убедитесь, что хотя бы один из ваших тестовых случаев использует метод `verifyDefaultAdapter`, определенный с помощью наших [помощников для основ](../testing/helpers/foundation.ts). Это делается для того, чтобы убедиться, что интерфейсы адаптеров не изменяются непреднамеренно.

#### Использование вспомогательных методов
У нас есть модули-помощники в [testing/helpers](../testing/helpers) для таких вещей, как запуск тестов для основ, перехват методов адаптеров для прослушивания событий и работа с `requestAnimationFrame`. Мы рекомендуем использовать их в вашем коде для того, чтобы сделать написание тестов как можно более простым!#### Использование `getFixture` для фикстур DOM
Чтобы создать фикстуры для тестов компонентов/адаптеров, используйте вспомогательный метод [#getFixture](../testing/dom/index.ts).

#### Всегда очищайте DOM после каждого теста
Это важно. _Перед завершением теста убедитесь, что все элементы, прикрепленные к DOM, были удалены_.