# Атрибуты виджета

> Все атрибуты <tolkly-chat>, свойства цветов --tolkly-* и <tolkly-search>.

`<tolkly-chat>` нужны только два атрибута: `endpoint` и `project`. Остальное приходит с сервера
(`GET /v1/projects/<project>/widget`): название проекта, приветствие, тема и кто отвечает. Всё
это владелец проекта задаёт в приложении, в разделе проекта **Виджет**, с живым предпросмотром.
Атрибуты ниже нужны, если сайт хочет задать своё.

## Атрибуты
| Атрибут | Что делает |
|---|---|
| `endpoint` | Origin сервера Tolkly, `https://api.tolkly.io`. Без него — origin, с которого загружен `widget.js`. |
| `project` | ID проекта. Обязателен. |
| `name` | Задаёт заголовок чата и название сайта в его фразах. Без него — название проекта. |
| `greeting` | Заменяет первую фразу чата фразой сайта. |
| `handoff` | Ссылка на поддержку сайта. Чат предлагает её, когда у проекта нет операторов в Tolkly. Работают только ссылки `https:`, `http:`, `tg:` и `mailto:`, остальные игнорируются. В ссылку на `t.me` номер заявки из вопроса попадает параметром `start`. |
| `teaser` | Подсказка в одну строку над закрытым чатом, вместо заданной в «Виджете». Показывается один раз за сессию браузера. Исчезает, когда посетитель её скрыл или открыл чат. |
| `open` | Чат сразу открыт, но не забирает фокус страницы. |
| `position` | `left` или `right`: угол кнопки и окна вместо выбранного в «Виджете» ([Расположение](#placement)). |
| `inline` | Встраивает открытый чат в страницу по размеру контейнера: без кнопки и без закрытия. Задайте контейнеру высоту. |
| `launcher` | `none`: без кнопки и подсказки в углу. Чат по-прежнему открывается там, но из вашего элемента через `open()`; непрочитанные ответы показывайте по событию [`tolkly:unread`](https://tolkly.io/docs/ru/widget-api.md#tolkly-unread). |
| `lang` | Язык чата вместо `<html lang>` ([Язык](https://tolkly.io/docs/ru/widget-api.md#language)). |
| `theme` | Светлая или тёмная ([Светлая и тёмная тема](#light-dark)): `site` — как на странице, `system` — как в системе посетителя, `light` и `dark` — всегда одна. Без него — выбор в «Виджете», по умолчанию `site`. |
| `send-icon` | Значок кнопки отправки: `arrow` (вверх), `plane` (самолётик) или `forward` (вправо), вместо выбранного в «Виджете». Любое другое значение — стрелка. |
| `collapse` | Сколько утверждений ответа видно сразу, остальные сворачиваются. По умолчанию `3`; `0` — не сворачивать. |
| `data-identity` | Токен, который сервер вашего сайта подписал для посетителя ([Подпись посетителя](https://tolkly.io/docs/ru/identity.md)). |
| `nonce` | Nonce стилей из вашей Content-Security-Policy. Нужен браузерам без constructed stylesheets (Safari до 16.4). Без него виджет берёт nonce первого `<script nonce>` на странице ([CSP](https://tolkly.io/docs/ru/csp.md#nonces)). |
| `preview` | Рисует чат так, как его видят посетители, но ничего не отправляет и не восстанавливает сохранённый разговор. Нужен для предпросмотра виджета в приложении, не для рабочего сайта. |

Для `name`, `greeting`, `teaser`, `theme`, `send-icon` и `position` атрибут на теге важнее
настройки с сервера. Кто отвечает — ИИ или только люди, — на теге задать нельзя. Это решает
только переключатель в проекте.

Элемент сразу реагирует на смену `lang`, `name`, `data-identity` и `theme`. Остальные атрибуты
задавайте в разметке.

Как чат приводит посетителя к человеку:

- есть `handoff`, а операторов в Tolkly нет — по этой ссылке;
- есть операторы — чат передаёт разговор им;
- нет ни того, ни другого — чат просит у посетителя контакт (тех видов, что разрешены в проекте),
  чтобы ваша команда ответила.

## Цвета и шрифт
Тема — это набор CSS custom properties на элементе. Сервер присылает те, что прочитал с сайта, с
поправками владельца из приложения. Свои значения задайте в атрибуте `style` тега:

```html
<tolkly-chat endpoint="https://api.tolkly.io" project="your-project"
  style="--tolkly-accent: #0b7a53; --tolkly-radius: 8px"></tolkly-chat>
```

Цвета с сервера лежат внутри виджета, ниже всего, что задаёт ваша страница: значение в атрибуте
`style` и правило из вашей таблицы стилей (`tolkly-chat { --tolkly-accent: … }`) важнее, без
`!important`.

| Свойство | По умолчанию (светлая) | Для чего |
|---|---|---|
| `--tolkly-accent` | `#4f46e5` | кнопка, сообщения посетителя, нажатые элементы управления |
| `--tolkly-accent-fg` | `#ffffff` | текст на акцентном цвете |
| `--tolkly-accent-text` | акцентный цвет | текст и обводки акцентного цвета на фоне: метки источников, фокус |
| `--tolkly-bg` | `#ffffff` | фон окна |
| `--tolkly-fg` | `#16181d` | текст |
| `--tolkly-muted` | `#667085` | второстепенный текст |
| `--tolkly-border` | `#e4e7ec` | рамки |
| `--tolkly-surface` | `#f6f7f9` | карточки, код, цитаты источников |
| `--tolkly-radius` | `12px` | углы окна (в приложении — «Скругление»). Мелкие элементы управления берут то же значение, но не больше 12px. Поле ответа обнимает свои кнопки с запасом в 5px. |
| `--tolkly-font` | `system-ui, …` | шрифт текста; семейство, которое страница уже загружает |
| `--tolkly-mono` | `ui-monospace, …` | код |

Ваше значение действует в обеих схемах. Чтобы задать его только для одной, выберите её по
`data-scheme` ([Светлая и тёмная тема](#light-dark)).

## Светлая и тёмная тема
У чата две палитры, светлая и тёмная. Сервер присылает обе: цвета, прочитанные с вашего сайта, и
его тёмную (или светлую) тему, если она на сайте есть, — из правил `prefers-color-scheme` и классов
вроде `.dark`. Если её нет, вторая палитра собирается из ваших цветов: фирменный цвет сохраняет
оттенок и остаётся читаемым на новом фоне.

Какая показывается, решает атрибут `theme`, а без него — выбор в «Виджете» («Светлая или тёмная»):

| Значение | Чат |
|---|---|
| `site` (по умолчанию) | как страница под ним: по цвету её фона, затем по классу `dark` или `light` и атрибутам `data-theme`, `data-bs-theme`, `data-color-mode` на `<html>` или `<body>`, затем по её `color-scheme`. Переключается вместе с переключателем темы на вашем сайте. |
| `system` | как в системе посетителя. |
| `light`, `dark` | всегда эта палитра. |

Палитру, которую чат показывает, он ставит на тег: `data-scheme="light"` или `data-scheme="dark"`.
Ваш переключатель может управлять чатом через атрибут:

```js
document.querySelector('tolkly-chat').setAttribute('theme', isDark ? 'dark' : 'light')
```

Свои цвета для одной схемы задайте в таблице стилей:

```css
tolkly-chat[data-scheme="dark"] { --tolkly-bg: #0f172a; --tolkly-accent: #60a5fa; }
```


## Расположение
Чат стоит в правом нижнем углу, в 20 px от краёв страницы. Владелец проекта может перенести его в
приложении: в **Виджет** → «Расположение» задаются угол и отступы сбоку и снизу, от 0 до 400 px.
Все страницы получают эту настройку с сервера. Страница может задать своё на теге:

```html
<tolkly-chat endpoint="https://api.tolkly.io" project="your-project" position="left"
  style="--tolkly-offset-x: 24px; --tolkly-offset-y: 96px"></tolkly-chat>
```

| Свойство | По умолчанию | Что сдвигает |
|---|---|---|
| `--tolkly-offset-x` | `20px` | кнопку и окно от бокового края страницы (правого, или левого с `position="left"`) |
| `--tolkly-offset-y` | `20px` | кнопку от нижнего края; окно и подсказка остаются на 68 px выше неё |

В отличие от цветов, отступы работают и из вашей таблицы стилей. Там они важнее настройки
владельца даже без `!important`. Например, если на телефоне внизу страницы меню, чат можно
поднять только на телефонах:

```css
@media (max-width: 600px) {
  tolkly-chat { --tolkly-offset-y: 80px; }
}
```

Подходит любая CSS-длина, в том числе `calc(env(safe-area-inset-bottom) + 64px)`. На экране уже
600 px открытый чат занимает весь экран, поэтому там отступы сдвигают только кнопку.

Пока не пришли настройки проекта (не дольше 1,5 с), кнопка не рисуется. Иначе она появилась бы в
углу по умолчанию, а потом перепрыгнула в угол владельца.

## `<tolkly-search>`
Тот же скрипт добавляет окно поиска по страницам проекта, для сайтов документации:

```html
<tolkly-search endpoint="https://api.tolkly.io" project="your-project"></tolkly-search>
```

Элемент рисует на своём месте кнопку «Поиск по документации ⌘K».

- Окно открывается по этой кнопке или по Cmd+K (Ctrl+K) в любом месте страницы. Escape его
  закрывает.
- Страницы показываются по мере ввода. Enter просит ответ с источниками.
- Элемент принимает `endpoint`, `project`, `lang`, `theme` и свойства `--tolkly-*`. Настройки с
  сервера он не читает: без `theme` он следует за страницей, в собственных цветах виджета.
- `open(question?)` открывает окно, а с вопросом сразу его задаёт. `close()` закрывает.
- Код поиска загружается только на странице, где есть этот элемент.