/**
 * Kinjo — JS API карты ЖК на сайте застройщика. Типы для TypeScript: https://map.kinjo.ru/kinjo.d.ts
 * Документация: docs/embed-api.md. Протокол — версия 1 (Kinjo.protocol).
 *
 *   <div id="kinjo-map" style="height:600px"></div>
 *   <script src="https://map.kinjo.ru/widget.js"></script>
 *   <script>
 *     const map = Kinjo.mount('#kinjo-map', { project: 'dom-na-yamskoy' });
 *     map.on('houseSelect', (house) => console.log(house?.name, house?.sales?.priceText));
 *   </script>
 *
 * Страница квартиры (#53) — только ЖК с подсвеченным домом квартиры и кнопка «Открыть карту» (полная карта модалкой):
 *     Kinjo.mount('#flat-map', { project: 'atlas-unique', house: 'Дом 2', view: 'house' });
 *
 * Подключить в проекте: скачайте файл рядом с кодом (например, types/kinjo.d.ts) — window.Kinjo станет типизированным.
 */

export type KinjoMapTheme = 'light' | 'dark' | 'mono' | 'warm' | 'brand';
export type KinjoMode = '2d' | '3d';
/** Категория мест: id или подпись («Школы и сады»). */
export type KinjoCategory = 'edu' | 'shops' | 'health' | 'transport' | 'leisure' | (string & {});
export type KinjoControl = 'header' | 'categories' | 'time' | 'city' | 'route' | 'walk' | 'mapButtons' | 'compass' | 'card';
/** Какие наши элементы управления показывать: 'none' (или false) — только карта; { time: false } — всё, кроме времени. */
export type KinjoControls = 'none' | 'all' | boolean | Partial<Record<KinjoControl, boolean>>;
/** Форма пинов мест: pin — значок с точкой на земле (как было), badge — значок без точки, dot — компактная метка. */
export type KinjoPinShape = 'pin' | 'badge' | 'dot';

export interface KinjoMountOptions {
  /** Проект (адрес карты в кабинете): ?project=<slug>. Обязательно. */
  project: string;
  /** Тема карты. По умолчанию — как в проекте. */
  theme?: KinjoMapTheme;
  /** 2D — плоская карта (быстрее), 3D — сцена с солнцем и тенями. По умолчанию — как в проекте. */
  mode?: KinjoMode;
  /** Раскладка: dock — панель снизу, sidebar — боковая панель (sidebar:theme — в цвете интерфейса). */
  layout?: string;
  /** Категории на компьютере: icons — значки, legend — легенда. */
  dock?: 'icons' | 'legend';
  /** Шапка: full — логотип и название, logo — только логотип, none — без шапки. */
  logo?: 'full' | 'logo' | 'none';
  /** «Пешком за N минут»: [15, 30] или 'off'. */
  isochrones?: number[] | string;
  /** Пин ЖК с фото: '3d,pin', 'off' … */
  hero?: string;
  /** Высота блока: число px или 'auto' (по содержимому на телефоне). По умолчанию 560. */
  height?: number | 'auto';
  /** Подпись блока для экранного диктора. */
  title?: string;
  /** Наши элементы управления. По умолчанию — все. */
  controls?: KinjoControls;
  /** Форма пинов мест. По умолчанию — как в проекте. */
  pinShape?: KinjoPinShape;
  /** Скругление пинов, % от стороны: 0 — квадрат, 50 — круг. По умолчанию — как в проекте. */
  pinRadius?: number;
  /** Размер пинов: s, m, l. По умолчанию — как в проекте. */
  pinSize?: 's' | 'm' | 'l';
  /**
   * Скругление интерфейса, px (0–24): док, кнопки карты, карточки, плашки, панели, лист на телефоне — под стиль сайта.
   * 0 — прямые углы, 24 — капсулы. По умолчанию — как в проекте.
   */
  uiRadius?: number;
  /**
   * Размер дока — нижней капсулы со временем, «Городом», «Маршрутом» и категориями: m — стандартный, s — маленький,
   * xs — очень маленький. Больше стандартного не бывает. По умолчанию — как в проекте.
   */
  dockSize?: 'm' | 's' | 'xs';
  /**
   * Время суток открыто сразу: лента часов с ▶ видна при входе капсулой над доком, «☀» её сворачивает. false — лента
   * по нажатию на «☀». По умолчанию — как в проекте.
   */
  timeOpen?: boolean;
  /**
   * Цены, квартиры и свои строки карточек корпусов: { 'k1' | 'Корпус 1': {…} }. Живут только на странице сайта —
   * на сервер Kinjo не уходят. Перекрывают заполненное в кабинете.
   */
  houses?: Record<string, KinjoPageHouse>;
  /** true — загрузить карту, когда блок долистают (команда загрузит раньше). По умолчанию — сразу. */
  lazy?: boolean;
  /**
   * Вид карты. 'house' — для страницы квартиры: только ЖК с подсвеченным домом (house), без мест, категорий, солнца,
   * шапки и карточек, спокойный ракурс на дом; вращать и приближать можно (на компьютере колесо — с Ctrl/⌘, на
   * телефоне — двумя пальцами). Кнопка «Открыть карту» в углу открывает полную карту модалкой: тот же дом выбран, его
   * карточка открыта, данные houses — и в ней. Высота — у блока (CSS) или height, по умолчанию 420 px.
   */
  view?: 'house';
  /** Дом квартиры (view: 'house'): ID, ID части, название или подпись — как в selectHouse. */
  house?: string | number;
  /** Секция или подъезд дома квартиры (view: 'house'): подсветить только эту часть, если дом из частей. */
  section?: string;
  /** Подпись кнопки «Открыть карту» (view: 'house'); false — без кнопки. */
  openLabel?: string | false;
}

/** Данные корпуса со страницы сайта. Всё необязательно; null — убрать поле, заполненное в кабинете. Только текст. */
export interface KinjoPageHouse {
  /** «Цена от», ₽: число или строка «5 200 000». */
  priceFrom?: number | string | null;
  flatsOnSale?: number | string | null;
  /** Ссылка «Смотреть квартиры»: только https. */
  url?: string | null;
  /** Примечание под ценой, до 200 знаков: «Скидка 5% до 31.10». */
  note?: string | null;
  /** Подпись кнопки, до 40 знаков: «Выбрать квартиру». Без неё — «Смотреть квартиры», у нежилого дома (стилобат, коммерция, офисы) — «Смотреть помещения». */
  button?: string | null;
  /** Свои строки карточки, до 6: [{ label: 'Сдача', value: 'IV кв. 2026' }]. */
  lines?: { label: string; value: string }[] | null;
}

export interface KinjoHousesResult {
  /** ID домов, к которым применилось. */
  applied: string[];
  /** Ключи, для которых корпус не нашёлся. */
  unknown: string[];
  /** Что пропущено и почему. */
  warnings: string[];
}

export interface KinjoSales {
  /** Ссылка на выдачу квартир корпуса (с utm_source=kinjo). */
  url: string | null;
  /** «Цена от», ₽. */
  priceFrom: number | null;
  /** Квартир в продаже. */
  flatsOnSale: number | null;
  note: string | null;
  button: string | null;
  lines: { label: string; value: string }[];
  /** Когда обновили в кабинете (ISO 8601); со страницы — null. */
  updatedAt: string | null;
  /** page — есть данные со страницы сайта, cabinet — только из кабинета. */
  source: 'page' | 'cabinet' | null;
  /** «от 5,2 млн ₽». */
  priceText: string | null;
  /** «12 квартир в продаже». */
  flatsText: string | null;
}

export interface KinjoHouse {
  /** ID дома — тот же, что в кабинете и в API продаж. */
  id: string;
  name: string;
  /** Подпись над крышей. */
  label: string;
  floors: number | null;
  /** Очередь. */
  queue: string | null;
  status: 'built' | 'construction' | 'project';
  /** Срок сдачи: «4 кв. 2027», «Сдан». */
  deadline: string | null;
  /** Ссылка «Смотреть квартиры» (продажи или ссылка корпуса из модели). */
  url: string | null;
  /** Продажи — если застройщик их задал. */
  sales: KinjoSales | null;
}

export interface KinjoReady {
  version: number;
  project: string;
  title: string;
  mode: KinjoMode | null;
  houses: KinjoHouse[];
  categories: { id: KinjoCategory; label: string; count: number }[];
  /** Зоны «пешком за N минут», которые можно включить setWalkZone. */
  walkZones: number[];
  /** Есть ли «Город» (аэропорт, вокзал, центр). */
  city: boolean;
  /** Работает ли «Маршрут до адреса». */
  route: boolean;
  /** Часовой пояс ЖК, минуты от UTC: время в setTime и timeChange — по нему. */
  utcOffsetMinutes: number;
}

export interface KinjoTime {
  /** YYYY-MM-DD по времени ЖК. */
  date: string;
  /** «13:00». */
  time: string;
  minutes: number;
}

export interface KinjoPlace {
  name: string;
  kind: string;
  kindLabel: string;
  category: KinjoCategory;
  lngLat: [number, number];
  /** «≈ 7 мин пешком»; у места прямо в ЖК — null (маршрут к нему не строится). */
  walk: string | null;
  /** Место прямо в ЖК: арендатор первого этажа, двор — без маршрута, времени и расстояния. */
  inComplex: boolean;
}

export interface KinjoRoute {
  /** Откуда маршрут: место рядом, «Город» или адрес. */
  kind: 'place' | 'city' | 'address';
  to: string;
  lngLat: [number, number];
  mode: 'walk' | 'drive';
  minutes: number | null;
  km: number | null;
  approx?: boolean;
}

export interface KinjoError {
  code: string;
  message: string;
}

export interface KinjoEvents {
  ready: KinjoReady;
  /** Выбрали дом на карте или командой; null — выбор сняли. */
  houseSelect: KinjoHouse | null;
  placeSelect: KinjoPlace;
  routeBuilt: KinjoRoute;
  routeClear: { kind: 'place' | 'city' | 'address' };
  /** Время на карте (3D), не чаще 4 раз в секунду. */
  timeChange: KinjoTime;
  modeChange: { mode: KinjoMode };
  /** Нажали «Смотреть квартиры». */
  flatsClick: { id: string; name: string; url: string };
  /** Страница квартиры (view: 'house'): нажали «Открыть карту»; house — ключ дома квартиры. */
  mapOpen: { house: string | null };
  /** Страница квартиры: полную карту закрыли (✕, Esc, «назад», свайп). */
  mapClose: null;
  error: KinjoError;
}

export interface KinjoCamera {
  center?: [number, number];
  /** Масштаб карты; ближе предела приближения проекта (по умолчанию 17 или масштаб стартового вида, если он ближе) камера не подойдёт. */
  zoom?: number;
  bearing?: number;
  pitch?: number;
  /** мс. */
  duration?: number;
}

/** Ошибка команды: error.code — not_ready, unknown_house, bad_args, unavailable, route_failed, origin_not_allowed, timeout. */
export interface KinjoCallError extends Error {
  code: string;
}

export interface KinjoMap {
  readonly version: number;
  /** Блок (Kinjo.mount) или null (Kinjo.connect). */
  readonly el: HTMLElement | null;
  readonly iframe: HTMLIFrameElement | null;
  /** Карта загрузилась (данные события ready). */
  readonly ready: Promise<KinjoReady>;

  on<K extends keyof KinjoEvents>(name: K, fn: (data: KinjoEvents[K]) => void): this;
  off<K extends keyof KinjoEvents>(name: K, fn: (data: KinjoEvents[K]) => void): this;
  once<K extends keyof KinjoEvents>(name: K, fn: (data: KinjoEvents[K]) => void): this;

  /** Выбрать дом по ID, ID части, названию или подписи («Корпус 1»): карточка и камера к нему. */
  selectHouse(ref: string | number): Promise<KinjoHouse>;
  clearSelection(): Promise<null>;
  flyTo(camera: KinjoCamera): Promise<null>;
  /** Начальный вид проекта. */
  resetView(): Promise<null>;
  /** «13:00» — время суток, Date или ISO — день и время (по времени ЖК). В 2D запоминается для 3D (ответ null). */
  setTime(time: string | Date): Promise<KinjoTime | null>;
  /** «2026-06-21» или Date — день (время суток то же). */
  setDate(date: string | Date): Promise<KinjoTime | null>;
  setMode(mode: KinjoMode): Promise<{ mode: KinjoMode }>;
  setTheme(theme: KinjoMapTheme): Promise<{ theme: KinjoMapTheme }>;
  /** Показать только эти категории мест. */
  showCategories(categories: KinjoCategory[]): Promise<{ shown: KinjoCategory[] }>;
  showAllPlaces(): Promise<{ shown: KinjoCategory[] }>;
  /** Маршрут от ЖК до адреса (первая подсказка поиска по городу) или до точки. */
  routeTo(to: { address: string } | { lngLat: [number, number]; label?: string }, options?: { mode?: 'walk' | 'drive' }): Promise<{ mode: 'walk' | 'drive'; minutes: number; km: number; label: string; lngLat: [number, number] }>;
  clearRoute(): Promise<null>;
  /** Открыть «Город» (false — закрыть). */
  openCity(open?: boolean): Promise<null>;
  /** «Пешком за N минут» (одна из ready.walkZones); null — убрать. */
  setWalkZone(minutes: number | null): Promise<null>;
  /** Данные корпусов со страницы — целиком (прежние со страницы заменяются). */
  setHouses(houses: Record<string, KinjoPageHouse>): Promise<KinjoHousesResult>;
  /** Данные одного корпуса поверх прежних; null — убрать данные страницы у корпуса. */
  updateHouse(ref: string, house: KinjoPageHouse | null): Promise<KinjoHousesResult>;
  /** Наши элементы управления на лету. */
  setControls(controls: 'none' | 'all' | Partial<Record<KinjoControl, boolean>>): Promise<{ hidden: KinjoControl[] }>;
  getState(): Promise<{ mode: KinjoMode; house: KinjoHouse | null; time: KinjoTime | null; hidden: KinjoControl[] }>;
  /** Убрать карту (Kinjo.mount) или отключиться (Kinjo.connect). */
  destroy(): void;
}

export interface KinjoStatic {
  version: number;
  protocol: number;
  /** Блок по параметрам (или по data-атрибутам элемента) → объект карты. */
  mount(el: HTMLElement | string, options?: KinjoMountOptions): KinjoMap;
  /** Свой iframe с картой (https://map.kinjo.ru/?project=…&embed=1). origin — адрес карты, если не из src. */
  connect(iframe: HTMLIFrameElement | string, options?: { origin?: string }): KinjoMap;
  unmount(el: HTMLElement): void;
  /**
   * Новые параметры блока: квартира и дата — на лету; проект, тема и вид элементов (pinShape, pinRadius, pinSize,
   * uiRadius, dockSize, timeOpen) — перезагрузкой карты.
   */
  update(el: HTMLElement, params: Partial<KinjoMountOptions> & Record<string, unknown>): void;
  scan(): void;
}

declare global {
  interface Window {
    Kinjo: KinjoStatic;
  }
  const Kinjo: KinjoStatic;
}