Stsezhka

Appearance

Use Case #15: Текстовые подсказки / Cue Sheets (Вшиваем «шпаргалки» в файл) ​

1. Жизненная ситуация (Боль пользователя) ​

Представь: Пользователь готовится к сложному велопоходу или пробежке. Он внимательно изучает спутниковые снимки на твоем сайте и замечает важные детали:

  • "Ага, вот на 35-м километре развилка, указателей нет, главное не уехать направо в тупик!".
  • "Вот тут, на 70-м километре, будет жуткий спуск по камням, нужно заранее сбросить скорость."
  • "А возле этой фермы бегает огромная злая собака, надо проехать быстро."

В чем проблема: Как не забыть всё это в лесу? Сейчас люди пишут эти заметки на куске малярного скотча и клеят себе на раму велосипеда. В лесу идет дождь, скотч отклеивается, человек пролетает нужный поворот или падает на спуске. Мечта юзера: "Вот бы можно было прямо на сайте приклеить виртуальный стикер на дорогу, и чтобы мой навигатор САМ напомнил мне об этом в лесу!".

2. Как это ДОЛЖНО работать у тебя (UX-Магия) ​

Мы даем юзеру возможность лепить виртуальные "стикеры" прямо на синюю линию маршрута.

Сценарий (На сайте):

  1. Юзер наводит мышку на 70-й километр (прямо на синюю линию).
  2. Кликает правой кнопкой мыши. Появляется меню, он нажимает 📝 «Добавить подсказку».
  3. В появившемся окошке пишет: "Сбавь скорость! Камни!" и выбирает иконку "Восклицательный знак" ⚠️.
  4. На синей линии повисает красивый желтый стикер. Юзер скачивает GPX.

МАГИЯ В ЛЕСУ (В реальности): Юзер закинул файл в свой велокомпьютер (Garmin). Едет, крутит педали, забыл обо всем на свете. И вдруг, за 100 метров до спуска, навигатор громко ПИЩИТ (ПИП-ПИП!), экран загорается, и на нем крупными буквами: «⚠️ СБАВЬ СКОРОСТЬ! КАМНИ!». Юзер жмет по тормозам, аккуратно съезжает вниз и думает: "Господи, какой же гениальный сайт! Он спас мне жизнь!".

3. СЕКРЕТ ДЛЯ ПРОГРАММИСТА (Как засунуть текст в бездушный файл) ​

Кажется, что для этого нужно сложное мобильное приложение. Но НЕТ! Всё делается просто правильным формированием текстового GPX-файлика.

Инструкция для кода:"Внутри GPX-файла есть два разных «ящика». Первый называется <trk> (Track) — там лежат тысячи координат самой синей линии. Второй называется <wpt> (Waypoints, Точки интереса) — он придуман для независимых флажков. Когда юзер добавляет подсказку, мы не ломаем синюю линию! Мы просто берем текст юзера и кладем его во второй ящик <wpt>, прямо в тег названия <name>."

Внутри файла это выглядит так:

xml
<wpt lat="55.7512" lon="37.6184">
  <name>Сбавь скорость!</name>
  <sym>Danger</sym> 
</wpt>

(Тег <sym> говорит навигатору, какую иконку нарисовать. Если написать туда стандартное слово "Danger", Garmin сам достанет картинку восклицательного знака).

4. Два важных правила (Чтобы всё точно сработало) ​

Правило №1: Жесткий лимит текста (Защита от графоманов) ​

Экраны у старых велокомпьютеров — крошечные. Если написать поэму "Здесь очень опасная яма, Вася сломал колесо", навигатор зависнет или обрежет текст до "Здесь очень...", и юзер ничего не поймет. Что должен сделать сайт: В окошке добавления установи жесткий лимит — максимум 15-20 символов. Под полем выведи счетчик: Осталось: 4 символа. Заставляй писать коротко: "СОБАКА!", "ЯМА!", "ВОДА ТУТ".

Правило №2: Идеальный магнит (Snapping) ​

Опасность: Юзер кликает мышкой на 2 миллиметра в сторону от синей линии. В лесу это 50 метров. Юзер проедет мимо, а навигатор промолчит (он подумает: "Эта точка где-то в кустах, юзер туда не едет, не буду пищать"). Решение: Координата подсказки ОБЯЗАНА примагнититься (turf.nearestPointOnLine) и до миллиметра совпасть с координатой самой дороги.

Эпики и Задачи ​

Epic 1: UI Подсказок (Cue Sheets) на карте ​

  • Task 1.1: Добавить обработчик правого клика (contextmenu) на слой геометрии маршрута в MapLibre.
  • Task 1.2: Использовать turf.nearestPointOnLine, чтобы примагнитить клик строго к массиву геометрии.
  • Task 1.3: Отрисовать кастомный Popup для ввода текста с валидатором длины (макс 20 символов) и селектором базовых иконок (Danger, Left, Right, Water, Food).

Epic 2: State Management ​

  • Task 2.1: Создать в Zustand массив cuePoints: Array<{id, lng, lat, text, symbol}>.
  • Task 2.2: Отрисовывать эти точки на карте отдельным слоем маркеров поверх маршрута (желтые стикеры).

Epic 3: GPX XML Генератор ​

  • Task 3.1: При скачивании трека интегрировать массив cuePoints.
  • Task 3.2: Пройтись по массиву и сгенерировать ноды <wpt> (Waypoints) с тегами <name> и <sym>. Вставлять их в XML-документ перед тегом <trk>.
  • Task 3.3: Настроить маппинг UI-иконок в стандартные значения <sym> словаря Garmin/GPX (например, Danger, Drinking Water, Left, Right).