# Design

## Context

См. proposal.md — Why. Текущее состояние, формирующее подход:

- `lib/components/PhotoGrid.svelte` — `<ul class="grid">` с CSS-колонками по `density.cols`
  (2–8, фиксированное число, `lib/stores/density.svelte.ts`), ячейки — `<button>` с
  `aria-pressed`, `onclick`/`ondblclick`/`ondragstart`/`oncontextmenu`.
- `lib/stores/selection.svelte.ts` хранит `items: Photo[]` и `anchorId` (последний клик).
- `lib/components/AlbumPanel.svelte:25-27` выводит правую панель: маршрутное фото → панель
  фото; одно выбранное → панель фото; несколько → строки действий; иначе — свойства альбома.
- В сетке нет обработчиков клавиатуры и нет реакции на клик по пустому месту. Viewer уже задаёт
  «lightroom»-условности (стрелки, `Space`, `Enter`), но в другом маршруте.
- Сетка точечно решает геометрию по индексу, а действия (range, меню, drag, `goto`) живут в
  `routes/(app)/albums/[id]/+page.svelte`.

## Goals / Non-Goals

**Goals:**
- Курсор — состояние, отдельное от выделения; стрелки двигают только курсор.
- Клавиши `Space`/`Shift`+стрелки/`Enter`/`Esc` управляют выделением и просмотром.
- Клик по пустому месту сетки и её отступам снимает выделение и возвращает свойства альбома.
- Клавиатурная доступность без смены семантики существующих ячеек; поведение мыши сохраняется.

**Non-Goals:**
- Изменение контракта стора выделения или API/данных.
- Клавиатурная навигация на обзоре альбомов и в корзине.
- Изменение числа колонок сетки или адаптивного реflow.

## Decisions

### 1. Модель: курсор отдельно от выделения (B)
Выбран вариант B по решению пользователя: стрелки двигают курсор, выделение меняется только
`Space`/`Shift`+стрелки/кликом. Правая панель реагирует только на выделение, поэтому панель не
«мигает» при движении курсора. Альтернатива A (выделение следует за стрелками) отклонена.

### 2. Разделение ответственности: поверхность сетки в странице, PhotoGrid презентационен
Поверхность сетки — контейнер сетки вместе с отступами в `+page.svelte` (тот же, что нужен для
клика по пустому месту). Он владеет `keydown`/`click`/`focusin`/`focusout` и `tabindex="-1"`.
Обработчик `keydown` висит на этой поверхности (не на `window`) и работает, только когда фокус
внутри — это исключает столкновения с полями ввода, диалогами и Viewer. `PhotoGrid` остаётся
презентационным: принимает `cursorIndex` и `cursorVisible`, отдаёт `onCursorFocus(index)` на
`onfocus` ячейки, рисует контур курсора и roving `tabindex`. Страница хранит `cursorIndex` и
решает выделение, `loadMore`, `scrollIntoView`, `goto`.

```
keydown (поверхность сетки = контейнер + отступы)
   ├─ ArrowLeft/Right/Up/Down ──► moveCursor(next)        // курсор
   ├─ Shift+Arrow ──────────────► moveCursor(next, extend) // курсор + выделение
   ├─ Space ────────────────────► toggleCursor()
   ├─ Enter ────────────────────► goto(/albums/:id/photos/:i)
   └─ Esc ──────────────────────► selection.clear()

click (поверхность, вне [data-photo-cell] и органов управления)
   └─ selection.clear(); поверхность.focus()

onfocus ячейки ──► onCursorFocus(i)   // клик и Tab ставят курсор

страница (+page.svelte)
   cursorIndex: number | null   selection (store)   anchorId (store)
```

Альтернатива — держать курсор и `keydown` внутри `PhotoGrid` — отклонена: клик по пустому месту
должен покрывать отступы вокруг сетки, а `cursorIndex` нужен странице для `loadMore`, прокрутки и
синхронизации с мышью. Поэтому поверхностью становится контейнер страницы.

### 3. Геометрия по плоскому индексу
Сетка — плоский список в порядке документа, поэтому:

- `←`/`→` — `index ± 1`; на границе строки переход на соседнюю строку происходит естественно,
  отдельного случая не нужно; на краях сетки курсор остаётся на месте.
- `↑`/`↓` — `index ± density.cols`; если целевой индекс выходит за `[0, n-1]`, курсор остаётся
  на месте (без вертикального переноса). При наличии `nextCursor` движение вперёд загружает
  следующую порцию и только затем перемещает курсор.

Вычисление живёт в `PhotoGrid` (там известен `density.cols`); страница получает уже готовый
индекс.

### 4. Визуализация: рамка выделения + контур курсора
Выделение сохраняет `ring-2 ring-primary`. Курсор получает `data-cursor` и внешний
`outline-2 outline-offset-2` в токене `text` (контрастен во всех темах, включая нейтральную).
Оба состояния рисуются на одной ячейке без конфликта.

```
   selection        cursor            both
   +---------+     + - - - - +       + - - - - - +
   | [photo] |     | [photo] |       | +-------+ |
   | ring-pri|     | outline |       | |[photo]| |
   +---------+     + - - - - +       | +-------+ |
                                     + - - - - - +
```

Контур курсора показывается только при `:focus-within` сетки, чтобы не «зависал» после клика в
панели. Программный `.focus()` не гарантирует `:focus-visible`, поэтому видимость управляется
состоянием (`data-cursor`), а не нативным фокус-рингом.

### 5. Roving tabindex
Ячейка под курсором получает `tabindex="0"`, остальные — `-1`; при пустом курсоре `0` у первой
ячейки. Так Tab вводит фокус в сетку один раз, а внутренняя навигация — стрелками. Роли не
меняются: ячейки остаются `<button aria-pressed>`, что не ломает существующий a11y и мышь.

### 6. Снятие выделения кликом
Обработчик клика вешается на контейнер сетки вместе с отступами (обёртка `PhotoGrid` в
`+page.svelte`, а не `<body>`/`<main>`). Внутри: если `(e.target as Element).closest(
'[data-photo-cell]')` — выход; иначе `selection.clear()`. Клики по тулбару, рейлу и панелям
обработчик не видит физически. Чтобы стрелки работали сразу, контейнер получает
`tabindex="-1"` и `.focus()` после снятия.

### 7. Сброс и синхронизация с мышью
- Клик по фото выставляет и выделение, и `cursorIndex`.
- `ctrl`/`shift`-клик и контекстное меню также ставят курсор.
- При смене альбома `cursorIndex = null` (в том же `$effect`, где `selection.clear()`).
- Курсор не персистится.

### 8. Возврат фокуса из просмотра: однослотовая память
Просмотр и сетка — соседние маршруты, поэтому при возврате `+page.svelte` сетки монтируется
заново и теряет `cursorIndex`/выделение. Вводится модульный стор `lib/stores/viewer-return.ts` с
одним слотом `{ albumId, photoId }`:

```
маршрут просмотра ($effect на photoId) ──► viewerReturn.remember(albumId, photoId)
                                              (обновляется при каждом change)
сетка ($effect на albumId, в начале)     ──► viewerReturn.consume(albumId)
   ├─ вернул photoId этого альбома ──► после загрузки: selection=[photo], cursor=index,
   │                                    .focus() + scrollIntoView({block:'center'})
   │                                    (если фото нет — loadMore() пока не появится)
   └─ иначе ──► обычный пустой альбом, без автофокуса
```

Один слот, а не `Map`, сознательно: если после просмотра открыть другой альбом, слот
израсходуется и сбросится — «висячая» память не сработает на постороннем альбоме. Память
хранится в модуле (переживает навигацию/монтирование) и живёт только до следующего монтирования
сетки. Восстановление вызывается после `loading = false` и `await tick()`, иначе DOM-ячейки ещё
нет. Альтернатива — `history.state`/`sessionStorage` — отклонена: не покрывает браузерный Back.

## Risks / Trade-offs

- [Кольца выделения и курсора визуально спорят] → контур курсора с `outline-offset-2` снаружи
  рамки и в токене `text`; проверка в светлой, тёмной и нейтральной темах.
- [Стрелки перехватывают прокрутку `Space`] → `keydown` только на контейнере сетки;
  `preventDefault` для `Space` лишь при наличии курсора.
- [`↑`/`↓` при неполной последней строке] → если смещение на `density.cols` уводит за
  последнюю строку, курсор остаётся на месте, как требует сценарий вертикальных границ.
- [Курсор на ещё не загруженном фото] → при движении вперёд за последний загруженный и наличии
  `nextCursor` вызывается `loadMore()`, затем курсор ставится на новое фото; без `nextCursor` —
  курсор остаётся на месте.
- [Смена `density.cols` во время навигации] → индекс курсора хранится плоским, поэтому при
  изменении числа колонок `↑`/`↓` просто считают по новому значению; отдельного переселения не
  требуется.
- [Восстановление фокуса срабатывает не вовремя] → слот израсходуется при первом монтировании
  сетки и сбрасывается, если альбом не тот; восстановление выполняется после `loading = false`
  и `tick()`, поэтому ячейка уже в DOM.
- [Просмотренное фото вне первой страницы] → `restoreFocus` догружает страницы (`loadMore`) в
  цикле, пока фото не появится или пока не кончится `nextCursor`.

## Migration Plan

Только фронтенд, без изменений данных и API. Откат — удаление обработчиков и состояния курсора;
изменений в хранилище нет. Проверка: `cd frontend && npm run check` и ручной прогон в трёх темах.