From 62ef56ec945558f3caaa62578ad6fd62482726db Mon Sep 17 00:00:00 2001
From: Inna Belaya <neige@yandex-team.ru>
Date: Wed, 3 Dec 2014 14:34:20 +0300
Subject: [PATCH] radio description

---
 common.blocks/radio/radio.ru.md | 323 +++++++++++++++++++-------------
 1 file changed, 195 insertions(+), 128 deletions(-)

diff --git a/common.blocks/radio/radio.ru.md b/common.blocks/radio/radio.ru.md
index c8de42096..9da8cbf1b 100644
--- a/common.blocks/radio/radio.ru.md
+++ b/common.blocks/radio/radio.ru.md
@@ -1,194 +1,261 @@
 # radio
 
-Блок `radio` – «радиопереключатель», «радиокнопка». Используется для создания одиночных радиопереключателей.
+Используется в составе блока [radio-group](../radio-group/radio-group.ru.md) для создания радиопереключателей.
 
-В реализации блока используется функциональность нативного контрола `input` с атрибутом `type="radio"` – `<input name="name" type="radio">`, который скрывается при использовании модификатора `theme`.
+## Краткая информация
 
-В результате применения шаблонов, блок `radio` отображается на странице как HTML-тег `<label>`, содержащий:
+### Модификаторы блока
 
-* элемент `box` со скрытым контролом `input` (элемент `control`);
-* подпись к радиопереключателю, если задан BEMJSON-параметр `text`.
+| Модификатор | Допустимые значения | Способы использования | Описание |
+| ----------- | ------------------- | -------------------- | -------- |
+| <a href=#type>type</a> | <code>'button'</code> | <code>BEMJSON</code> | Тип радиопереключателя. |
+| <a href=#checked>checked</a> | <code>true</code> | <code>BEMJSON</code>, <code>JS</code> | Выбор радиопереключателя. |
+| <a href=#disabled>disabled</a> | <code>true</code> | <code>BEMJSON</code>, <code>JS</code> | Неактивное состояние. |
+| <a href=#focused>focused</a> | <code>true</code> | <code>BEMJSON</code>, <code>JS</code> | Фокус на блоке. |
+| <a href=#size>size</a> | <code>'m'</code>, <code>'l'</code> | <code>BEMJSON</code> | Размер радиопереключателя. |
+| <a href=#theme>theme</a> | <code>'islands'</code> | <code>BEMJSON</code> | Стилевое оформление. |
 
-## Специализированные поля блока
+### Специализированные поля блока
 
-Список зарезервированных полей входного BEMJSON:
+| Поле | Тип | Описание |
+| ---- | --- | -------- |
+| <a href=#name>name</a> | <code>String</code> | Имя радиопереключателя. |
+| <a href=#val>val</a> | <code>String</code> | Значение, возвращаемое радиопереключателем, если он выбран. |
+| <a href=#text>text</a> | <code>String</code> | Текст подписи к радиопереключателю. |
+| <a href=#icon>icon</a> | <code>BEMJSON</code> | Иконка. Формируется блоком <a href="../icon/icon.ru.md">icon</a>. Используется только для радиопереключателя с <a href=#type>модификатором type в значении button</a>. |
 
-<table>
-    <tr>
-        <th>Поле</th>
-        <th>Тип</th>
-        <th>Описание</th>
-    </tr>
-    <tr>
-        <td><code>name</code></td>
-        <td><code>String</code></td>
-        <td>Имя радиопереключателя, предназначено для того, чтобы обработчик формы мог его идентифицировать. Преобразуется в HTML-атрибут <code>name</code> вложенного блока <code>input</code>.</td>
-    </tr>
-    <tr>
-        <td><code>val</code></td>
-        <td><code>String</code></td>
-        <td>Определяет значение, которое будет отправлено на сервер или получено с помощью клиентских скриптов. На сервер отправляется пара «имя=значение», где имя задается ключом <code>name</code> тега `<input>`, а значение — ключом <code>val</code>.
-            <br>Преобразуется в HTML-атрибут <code>value</code> вложенного блока <code>input</code>.</td>
-    </tr>
-    <tr>
-        <td><code>text</code></td>
-        <td><code>String</code></td>
-        <td>Подпись к радиопереключателю.</td>
-    </tr>
-</table>
+## Обзор блока
 
-При необходимости дополнительные HTML-атрибуты блока могут быть заданы в зарезервированном поле `attrs` в BEMJSON.
+### Модификаторы блока
 
-## Модификаторы блока
+<a name="type"></a>
+##### Модификатор `type`
 
-### Темы `_theme`
+Допустимое значение: `'button'`.
 
-Блок представлен в следующих темах:
+Способ использования: `BEMJSON`.
 
- * simple
- * islands (**Важно:** При выборе темы `islands` необходимо указывать обязательный модификатор [size](#size).)
+Модификатор `type` в значении `button` используется для изменения внешнего вида блока на кнопочный. В таком случае выбор радиопереключателя происходит нажатием на [кнопку](../button/button.ru.md).
 
-Без указания модификатора `theme` отображается [нативный](#native) вид контрола.
+```js
+{
+    block : 'radio',
+    mods : { theme : 'islands', size : 'm', type : 'button' },
+    name : 'radio-islands',
+    val : 1,
+    text : 'Использовать BEMHTML'
+}
+```
+
+<a name="checked"></a>
+#### Модификатор `checked`
+
+Допустимое значение: `true`.
 
-Наглядно показано на примерах ниже:
+Способы использования: `BEMJSON`, `JS`.
 
-<a name="native"></a>
-**default**
+Модификатор `checked` в значении `true` используется для выбора радиопереключателя.
+
+```js
+{
+    block : 'radio',
+    mods : { theme : 'islands', size : 'm', checked : true },
+    name : 'radio-islands',
+    val : 1,
+    text : 'Использовать BEMHTML'
+}
+```
 
-```bemjson
+```js
 {
     block : 'radio',
-    name : 'radio-simple',
-    text : 'Radio switch'
+    mods : { theme : 'islands', size : 'm', type : 'button', checked : true },
+    name : 'radio-islands',
+    val : 1,
+    text : 'Использовать BEMHTML'
 }
 ```
 
-**simple**
+<a name="disabled"></a>
+#### Модификатор `disabled`
+
+Допустимое значение: `true`.
+
+Способы использования: `BEMJSON`, `JS`.
 
-```bemjson
+Модификатор `disabled` в значении `true` отвечает за неактивное состояние, при котором блок виден, но недоступен для действий пользователя.
+
+```js
 {
     block : 'radio',
-    mods : { theme : 'simple' },
-    name : 'radio-simple',
-    text : 'Radio switch'
+    mods : { theme : 'islands', size : 'm', disabled : true },
+    name : 'radio-islands',
+    val : 1,
+    text : 'Использовать BEMHTML'
 }
 ```
 
-**islands**
+```js
+{
+    block : 'radio',
+    mods : { theme : 'islands', size : 'm', type : 'button', disabled : true },
+    name : 'radio-islands',
+    val : 1,
+    text : 'Использовать BEMHTML'
+}
+```
 
-```bemjson
+<a name="focused"></a>
+#### Модификатор `focused`
+
+Допустимое значение: `true`.
+
+Способы использования: `BEMJSON`, `JS`.
+
+Модификатор `focused` в значении `true` отвечает за наличие фокуса на блоке.
+
+```javascript
 {
     block : 'radio',
-    mods : { theme : 'islands', size : 'm' },
+    mods : { theme : 'islands', size : 'm', focused : true },
     name : 'radio-islands',
-    text : 'Radio switch'
+    val : 1,
+    text : 'Использовать BEMHTML'
 }
 ```
 
-<a name="size"></a>
-### Размеры `_size`
-
-Реализован только в теме `islands`.
-
-В зависимости от значения модификатора `type` доступны следующие размеры реализации блока:
-
-<table>
-    <tr>
-        <th>Размер</th>
-        <th>Обычный радиопереключатель</th>
-        <th>Кнопочный радиопереключатель
-            <br>(<code>radio_type_button</code>)</th>
-    </tr>
-    <tr>
-        <th>s</th>
-        <td>–</td>
-        <td>+</td>
-    </tr>
-    <tr>
-        <th>m</th>
-        <td>+</td>
-        <td>+</td>
-    </tr>
-    <tr>
-        <th>l</th>
-        <td>+</td>
-        <td>+</td>
-    </tr>
-    <tr>
-        <th>xl</th>
-        <td>–</td>
-        <td>+</td>
-</table>
-
-
-### Тип `_type`
-
-Модификатор `type` со значением `button` используется для создания кнопочного радиопереключателя, реализованного на основе блока [button](../button/button.ru.md) с модификатором `button_togglable_radio`.
-
-При этом к блоку `button` примешивается блок `radio`, а контентом кнопки становится элемент `control`. Как следствие, для блока с модификатором `radio_type_button` доступны состояния блока `button`:
-
-*  `hovered` – под курсором;
-*  `pressed` – кнопка нажата.
-
-При установленном модификаторе `radio_type_button` блоку задается HTML-атрибут `role="button"`.
-
-```bemjson
+```javascript
 {
     block : 'radio',
-    mods : { theme : 'islands', size : 'm', type : 'button' },
+    mods : { theme : 'islands', size : 'm', type : 'button', focused : true },
     name : 'radio-islands',
-    text : 'radio switch'
+    val : 1,
+    text : 'Использовать BEMHTML'
 }
 ```
-### Состояния
 
-#### Выбран `_checked`
+<a name="size"></a>
+#### Модификатор `size`
+
+Допустимые значения для темы `islands`: `'m'`, `'l'`.
+
+Способ использования: `BEMJSON`.
 
-Модификатор `checked` указывает на то, что радиопереключатель выбран.
+Задает размер шрифта и отступов, либо размер кнопки.
 
-Модификатор устанавливается по:
+Модификатор `size` используется, только если блоку установлен модификатор <a href="#theme">theme</a> в значении `islands`.
 
-* щелчку мыши (при повторных щелчках модификатор сохраняется);
-* нажатию клавиш `Enter` или `Space`, если радиокнопка находится в фокусе (возможность использования клавиши `Enter` зависит от браузера);
-* нажатию клавиш стрелок, если фокус установлен на соседний радиопереключатель в радиогруппе или в блоке, содержащем несколько блоков `radio`.
+**m**
 
-```bemjson
+```js
 {
     block : 'radio',
-    mods : { theme : 'islands', size : 'm', checked : true },
-    name : 'radio-norma',
-    text : 'Radio switch'
+    mods : { theme : 'islands', size : 'm' },
+    name : 'radio-islands',
+    val : 1,
+    text : 'Использовать BEMHTML'
+}
+```
+
+```js
+{
+    block : 'radio',
+    mods : { theme : 'islands', size : 'm', type : 'button' },
+    name : 'radio-islands',
+    val : 1,
+    text : 'Использовать BEMHTML'
+}
+```
+
+**l**
+
+```js
+{
+    block : 'radio',
+    mods : { theme : 'islands', size : 'l' },
+    name : 'radio-islands',
+    val : 1,
+    text : 'Использовать BEMHTML'
+}
+```
+
+```js
+{
+    block : 'radio',
+    mods : { theme : 'islands', size : 'l', type : 'button' },
+    name : 'radio-islands',
+    val : 1,
+    text : 'Использовать BEMHTML'
 }
 ```
 
-#### Неактивен `_disabled`
+<a name="theme"></a>
+#### Модификатор `theme`
+
+Допустимое значение: `'islands'`.
 
-В состоянии «неактивен» блок виден, но недоступен для действий пользователя. Такой блок не может получить фокус путем нажатия на клавишу `Tab`, мышью или другими способами. В большинстве случаев к неактивному блоку применяются дополнительные стили, чтобы выделить его на странице.
+Способ использования: `BEMJSON`.
 
-При установке модификатора `disabled` для радиопереключателя не будут:
+Модификатор `theme` отвечает за стилевое оформление блока.
 
-* устанавливаться модификаторы состояния `hovered`, `pressed` и `focused`;
-* изменяться значение модификатора `checked`.
+При выборе модификатора `theme` в значении `islands` необходимо обязательно указывать модификатор <a href="#size">size</a>.
 
-```bemjson
+Без указания модификатора `theme` отображается нативный вид контрола.
+
+```js
+{
+    block : 'radio',
+    mods : { theme : 'islands', size : 'm' },
+    name : 'radio-islands',
+    val : 1,
+    text : 'Использовать BEMHTML'
+}
+```
+
+```js
 {
     block : 'radio',
-    mods : { theme : 'islands', size : 'l', disabled : true },
+    mods : { theme : 'islands', size : 'm', type : 'button' },
     name : 'radio-islands',
-    text : 'Radio switch'
+    val : 1,
+    text : 'Использовать BEMHTML'
 }
 ```
 
-#### В фокусе `_focused`
+### Специализированные поля блока
+
+<a name="name"></a>
+#### Поле `name`
 
-Модификатор `focused` в значении `true` автоматически выставляется блоку в момент, когда он находится в фокусе. Например, по нажатию клавиши `Tab` или при щелчке мышью.
+Имя радиопереключателя. Используется для того, чтобы обработчик формы мог его идентифицировать. Определяет значение поля `name`, отправляемое на сервер. Всегда отправляется в паре со значением поля `val`, чтобы клиентская или серверная программа могла однозначно установить, какой пункт выбрал пользователь.
 
-## Элементы
+<a name="val"></a>
+#### Поле `val`
 
-### `__box`
+Определяет значение поля `val`, отправляемое на сервер. Всегда отправляется в паре со значением поля `name`, чтобы клиентская или серверная программа могла однозначно установить, какой пункт выбрал пользователь.
 
-Элемент `box` используется в стандартной реализации блока как контейнер, содержащий контрол радиокнопки (элемент `control`). Вспомогательный скрытый элемент. Добавляется блоку на уровне шаблонизатора и становится HTML-элементом `<span>`.
+<a name="text"></a>
+#### Поле `text`
 
-### `__control`
+Определяет текст подписи к радиопереключателю.
 
-Элемент `control` – вспомогательный скрытый элемент. Добавляется блоку на уровне шаблонизатора и становится HTML-элементом `<input>` с атрибутом `type="radio"`.
+<a name="icon"></a>
+#### Поле `icon`
+
+Определяет иконку, которая отображается с помощью блока `icon`.
+
+Используется только для радиопереключателей с <a href=#type>модификатором type в значении button</a>.
+
+```js
+{
+    block : 'radio',
+    mods : { theme : 'islands', size : 'm', type : 'button' },
+    name : 'radio-islands',
+    val : 1,
+    text : 'twitter',
+    icon : {
+        block : 'icon',
+        mods : { social : 'twitter' }
+    },
+}
+```