Агентный слой
Запрос подтверждения
Определяющее взаимодействие агентных систем: агент останавливается и спрашивает разрешения. Всё остальное на экране можно проскроллить — это нельзя, поэтому блок единственный в библиотеке, кто имеет право останавливать глаз.
terrain/- heightmap.ts — перезапись
- chunks.bin — удаление
Разметка
<div class="inst-approval" data-state="pending" role="group" aria-labelledby="ap1">
<div class="inst-approval-head" id="ap1">Требуется подтверждение</div>
<div class="inst-approval-what">Записать 4 файла в <code>terrain/</code></div>
<ul class="inst-approval-effects">
<li>heightmap.ts — перезапись</li>
<li data-tone="error">chunks.bin — удаление</li>
</ul>
<div class="inst-approval-actions">
<button class="inst-btn inst-btn--sm inst-btn--primary" type="button">Разрешить</button>
<button class="inst-btn inst-btn--sm" type="button">Отклонить</button>
</div>
</div>
Контракт
Без любой из них компонент не выполняет свою работу и превращается в украшенное «вы уверены?».
| Что | Класс | Почему обязательно |
|---|---|---|
| Что именно будет сделано | inst-approval-what |
«Разрешить действие?» не является вопросом: пользователь не знает, на что отвечает |
| Что это затронет | inst-approval-effects |
Список последствий. Необратимые помечаются тоном error |
| Решение одним нажатием | inst-approval-actions |
Разрешить и отклонить рядом. Отсутствие «отклонить» превращает запрос в уведомление |
Доступность
| Группа | role="group" + aria-labelledby на заголовок. Иначе блок разваливается на несвязанные абзацы |
| Появление | Запрос возникает по инициативе машины, поэтому обязан попасть в живую область: aria-live="assertive" или перевод фокуса на блок. Тихо появившийся запрос будет ждать вечно |
| Порядок действий | «Разрешить» первым: главное действие идёт первым, и это единственный сигнал, какое из двух главное |
| Отклонение доступно всегда | Кнопка «Отклонить» не может быть спрятана в меню. Отказ должен стоить столько же нажатий, сколько согласие |
| Не только цвет | Необратимое последствие помечено тоном и словом («удаление»), а не одной краснотой |
| Фокус после ответа | Действия исчезают вместе с ответом — приложение обязано перевести фокус, иначе он провалится в <body> |
Устройство
<ul class="inst-approval-effects">
<li>heightmap.ts — перезапись</li>
<li data-tone="warn">config.json — изменение настроек</li>
<li data-tone="error">chunks.bin — удаление</li>
</ul>
Тон здесь означает необратимость. Удаление красное потому, что его нельзя отменить, — а не потому, что оно «плохое».
Состояния
Разметка
<div class="inst-approval" data-state="pending" role="group" aria-label="Ожидает">
<div class="inst-approval-head">Требуется подтверждение</div>
<div class="inst-approval-what">Записать 4 файла</div>
<div class="inst-approval-actions">
<button class="inst-btn inst-btn--sm inst-btn--primary" type="button">Разрешить</button>
<button class="inst-btn inst-btn--sm" type="button">Отклонить</button>
</div>
</div>
<div class="inst-approval" data-state="approved" role="group" aria-label="Разрешено">
<div class="inst-approval-head">Требуется подтверждение</div>
<div class="inst-approval-what">Записать 4 файла</div>
<div class="inst-approval-verdict">Разрешено в 14:32</div>
</div>
data-state |
Что происходит |
|---|---|
pending |
Ожидает ответа. Единственное, где показаны действия |
approved |
Разрешено. Блок отступает, действия скрыты |
denied |
Отклонено. Описание действия зачёркнуто |
После ответа блок не исчезает и не гаснет — он отступает. История решений остаётся читаемой: пользователь должен иметь возможность вернуться и увидеть, что именно он разрешил час назад. Исчезнувший запрос невозможно проверить.
JS
Подключите модуль один раз на страницу — инициализировать компоненты по
отдельности не нужно, instrument.js работает делегированием и видит узлы, пришедшие
позже.
<script type="module" src="instrument.js"></script>
Что делает instrument.js
Ничего. Здесь он честно не при чём: согласие на действие агента — это решение, а не поведение виджета, и подделать его оформлением нельзя.
Что должно сделать приложение
- Отправить решение туда, где оно исполняется.
- Перевести блок в решённое состояние — иначе кнопки останутся живыми и человек нажмёт второй раз.
- Оставить видимым, что было решено: блок согласия — это след в истории, а не диалог, который закрылся.
block.addEventListener('click', async (e) => {
const btn = e.target.closest('[data-decision]');
if (!btn) return;
for (const b of block.querySelectorAll('button')) b.disabled = true;
await api.decide(block.dataset.id, btn.dataset.decision);
block.dataset.decided = btn.dataset.decision;
});
Кнопки блокируются до запроса. Сеть занимает секунды, и за это время «Разрешить» успевают нажать дважды.
Сценарии
Запрос из настоящего прогона — с командой, списком последствий и пометкой необратимого.
Обратите внимание на порядок: что будет сделано, что это затронет, и только потом решение. Запрос, начинающийся с кнопок, требует ответа раньше, чем сообщает вопрос.
- Удалит каталог
build/целиком — 1 284 файла - Необратимо: содержимое не попадает в корзину
- Пересборка займёт около 40 с
Разметка
<div class="inst-approval" data-state="pending" role="group" aria-labelledby="ap2">
<div class="inst-approval-head" id="ap2">Агент просит разрешение</div>
<div class="inst-approval-what">rm -rf build/ && npm run build</div>
<ul class="inst-approval-effects">
<li>Удалит каталог <code>build/</code> целиком — 1 284 файла</li>
<li data-tone="warn">Необратимо: содержимое не попадает в корзину</li>
<li>Пересборка займёт около 40 с</li>
</ul>
<div class="inst-approval-actions">
<button class="inst-btn inst-btn--sm inst-btn--primary" type="button">Разрешить</button>
<button class="inst-btn inst-btn--sm" type="button">Отклонить</button>
<button class="inst-btn inst-btn--ghost inst-btn--sm" type="button">Разрешать всегда</button>
</div>
</div>
API
| Имя | Что делает |
|---|---|
| класс | |
inst-approval | Блок |
inst-approval-head | Заголовок со значком |
inst-approval-what | Что будет сделано |
inst-approval-effects | Список последствий, на <ul> |
inst-approval-actions | Решение |
inst-approval-verdict | Что решили и когда. Показывается после ответа |
| Имя | Значение | Что делает |
|---|---|---|
| атрибут | ||
data-state | pending · approved · denied | на inst-approval |
data-tone | warn · error | на <li> последствия |
| Имя | Значение | Откуда |
|---|---|---|
| токен | ||
--pad-card | var(--space-6) | база +14: плотность · масштаб |
--radius-lg | 12px | база +4: масштаб |
--space-3 | 6px | одно на все ячейки |
--gap-inline | var(--space-4) | база +14: плотность · масштаб |
--text-sm | 0.875rem | база +4: масштаб |
--text-xs | 0.78125rem | база +4: масштаб |
--warn-bg | light-dark(var(--warn-1), color-mix(in oklab, var(--warn-4) 16%, transparent)) | одно на все ячейки |
--warn-text | light-dark(var(--warn-5), var(--warn-3)) | база +1: тема |
--err-text | light-dark(var(--err-5), var(--err-3)) | база +1: тема |
--text-muted | light-dark(var(--n-8), var(--n-6)) | одно на все ячейки |
Почему кит устроен именно так — конституция · Открытый код под MIT, github.com/keshon/instrument