# @funboxteam/babel-plugin-typograf

[![npm](https://img.shields.io/npm/v/@funboxteam/babel-plugin-typograf.svg)](https://www.npmjs.com/package/@funboxteam/babel-plugin-typograf)

Babel-плагин для автоматического типографирования текста.

## Назначение

Текст — один из основных инструментов, используемых в интерфейсах для описания действия.
Помимо этого, зачастую страницы могут полностью состоять из текста в разных его проявлениях:
лэндинги, разделы «О сервисе» и «Вопросы на ответы» и подобные им. Фронтенд-разработчики должны 
не забывать о том, какие кавычки и чёрточки и когда использовать, когда ставить неразрывный пробел, 
а когда нет, и так далее.

Этот Babel-плагин нужен для автоматизации подобной рутины. Он улучшает типографику текста на этапе сборки проекта. 

## Установка

```bash
npm install --save-dev @funboxteam/babel-plugin-typograf
```

## Настройка

**Важно:**
В секции `plugins` этот плагин должен быть выше остальных, обрабатывающих шаблонные строки (например, `plugin-transform-template-literals`), чтобы конвертирование теговых шаблонов было выполнено раньше, чем начнётся работа этих плагинов над шаблонными строки.

После установки, необходимо добавить плагин в конфигурацию Babel:

```js
{
  plugins: [
    // ...
    ['@funboxteam/babel-plugin-typograf', {
      // Замена символов происходит с учётом локали
      locale: ['ru', 'en-US'],

      // Конвертация символов в HTML-сущности (по умолчанию отключена)
      htmlEntity: {
        type: 'name',        // 'name' или 'digit'
        onlyInvisible: true, // Установите `true`, чтобы конвертировать только невидимые символы
      },

      // Здесь можно включить дополнительные правила
      enableRules: [
        'common/nbsp/afterNumber',
      ],
      
      // А здесь отключить те, что включены по умолчанию в Typograf
      disableRules: [
        'common/punctuation/quote',
      ],

      // Настройки для правил
      ruleSettings: [
        ['common/nbsp/beforeShortLastWord', 'lengthLastWord', 8],
      ],
    }],
  ]
}
```

## Использование

Для обозначения строк, которые нужно обработать, используется специальный тег:

```js
// Исходная строка
T`Отформатированная "строка".  `;

// Строка после обработки плагином
// Теговый шаблон с тегом `T` конвертируется в обычную шаблонную строку
`Отформатированная «строка».`;
```

## Typograf

Для обработки текста плагин использует библиотеку [Typograf](https://github.com/typograf/typograf). 
Он ищет теговые шаблоны, помеченные тегом `T`:

```
T`"строка"`
```

Дорабатывает типографику внутри этих шаблонов, а затем конвертирует из в обычные шаблонные строки, удаляя тег:

```
`«строка»`
``` 

### Основные возможности Typograf

* Удаление лишних пробелов.
* Автоматическая расстановка неразрывных пробелов.
* Конвертация двойных кавычек в «ёлочки».
* Конвертация HTML-сущностей (` `, `«`, `»` и т.д.) в Unicode-символы.

### Правила Typograf

В Typograf есть [список правил](https://github.com/typograf/typograf/blob/dev/docs/RULES.ru.md), которые включены по умолчанию.  

#### Не рекомендуется включать

* `ru/money/ruble`  
  Преобразует все `руб.` в `₽`. 
  Рекомендуется указывать знак `₽` точечно во избежание рисков комплексной автозамены там, где это может не потребоваться. 
  Например, в динамических текстах, где необходимо указывать именно `руб.`, и которые отследить заранее практически невозможно. 
  Или в разметке, где требуется указать `руб.` в связи с тем, что знак `₽` корректно отображается не во всех используемых шрифтах.

* `common/space/delBeforePunctuation`  
  Удаляет пробелы перед знаками препинания. 
  Но есть нюанс.
  Например, фраза «Нам нужен .Net-разработчик.» превратится в «Нам нужен.Net-разработчик.». 
  На данный момент это решается только отключением правила, но, [возможно](https://github.com/typograf/typograf/issues/312), 
  в будущем можно будет добавлять исключения.
 
* `common/space/afterPunctuation`  
  Добавляет пробелы после знаков пунктуации. 
  Может добавить пробел в случаях, когда он не нужен. 
  Например, фраза `разделитель запятая «,»` превратится в `разделитель запятая «, »`, 
  а из-за этого неправильно сработает правило `common/punctuation/quote`, 
  и в результате получится `разделитель запятая «, «`.

[![Sponsored by FunBox](https://funbox.ru/badges/sponsored_by_funbox_centered.svg)](https://funbox.ru)