@russian-flags/moscow-oblast

English version

Нативная ESM-коллекция SVG-флагов городов Московской области. Пакет можно использовать как npm-зависимость в JavaScript/TypeScript-проекте или как набор SVG-файлов с ленивыми загрузчиками.

Список городов основан на странице Wikipedia "Городские населённые пункты Московской области": 74 города. Всего в пакете 74 записи.

SVG-флаги лежат в assets/<slug>/index.svg и доступны в собранном пакете как dist/flags/<slug>.svg.

Превью

| Город | Флаг | slug | | --- | --- | --- | | Балашиха | | balashiha | | Королёв | | korolev | | Подольск | | podolsk | | Сергиев Посад | | sergiev-posad | | Химки | | himki |

Возможности

• 74 локальных SVG-файла в структуре assets/<slug>/index.svg.
• ESM-сборка с TypeScript-типами.
• Ленивые загрузчики для каждого флага.
• Поиск флага по slug, коду, русскому/английскому названию или alias.
• Прямой импорт SVG через flags/<slug> или svg/<slug>.
• Подходит для JavaScript, TypeScript и современных сборщиков.

Установка

npm install @russian-flags/moscow-oblast

Для локальной проверки из папки проекта:

npm install .

Быстрый старт

import { loadFlag, settlements } from "@russian-flags/moscow-oblast";

console.log(settlements[0]);
// {
//   slug: "aprelevka",
//   code: "APRELEVKA",
//   nameRu: "Апрелевка",
//   nameEn: "Aprelevka",
//   aliases: [],
// }

const image = await loadFlag("balashiha", {
  alt: "Флаг Балашихи",
  className: "flag",
});

document.body.append(image);

loadFlag - алиас для loadFlagImage. Функция лениво импортирует модуль нужного флага, создаёт <img> и по умолчанию ставит loading="lazy" и decoding="async".

Подключение SVG напрямую

Если нужен только файл флага, SVG можно импортировать напрямую:

import balashihaFlag from "@russian-flags/moscow-oblast/flags/balashiha";
import balashihaSvg from "@russian-flags/moscow-oblast/svg/balashiha";

console.log(balashihaFlag);
console.log(balashihaSvg);

Вариант с расширением тоже поддерживается:

import balashihaFlag from "@russian-flags/moscow-oblast/flags/balashiha.svg";
import balashihaSvg from "@russian-flags/moscow-oblast/svg/balashiha.svg";

flags/<slug> и svg/<slug> указывают на один и тот же файл внутри пакета:

dist/flags/<slug>.svg

После публикации пакет также можно использовать как источник SVG через npm CDN:

<img src="https://unpkg.com/@russian-flags/moscow-oblast/dist/flags/balashiha.svg" alt="Флаг Балашихи" />

Поиск города

В большинство функций можно передавать:

• slug: "balashiha";
• код: "BALASHIHA";
• русское название: "Балашиха";
• английское название: "Balashikha";
• alias: "Korolev".

import {
  resolveSettlementSlug,
  settlementSlugs,
  settlements,
} from "@russian-flags/moscow-oblast";

console.log(settlements.length); // 74
console.log(settlementSlugs.includes("balashiha")); // true

console.log(resolveSettlementSlug("BALASHIHA")); // "balashiha"
console.log(resolveSettlementSlug("Балашиха")); // "balashiha"
console.log(resolveSettlementSlug("Balashikha")); // "balashiha"
console.log(resolveSettlementSlug("Korolev")); // "korolev"
console.log(resolveSettlementSlug("staraya_kupavna")); // "staraya-kupavna"
console.log(resolveSettlementSlug("unknown")); // undefined

Ввод нормализуется: пробелы по краям удаляются, регистр не важен, ё считается как е, пробелы и _ заменяются на -.

Ленивое отображение списка

import { loadFlag, settlements } from "@russian-flags/moscow-oblast";

for (const settlement of settlements) {
  const row = document.createElement("tr");
  row.dataset.slug = settlement.slug;
  row.textContent = settlement.nameRu;
  document.querySelector("tbody").append(row);
}

const observer = new IntersectionObserver((entries) => {
  for (const entry of entries) {
    if (!entry.isIntersecting) continue;

    observer.unobserve(entry.target);

    loadFlag(entry.target.dataset.slug).then((image) => {
      entry.target.append(image);
    });
  }
});

document
  .querySelectorAll("tr[data-slug]")
  .forEach((row) => observer.observe(row));

Preload

preloadFlag запускает загрузку модуля флага без ожидания результата. Это удобно на hover, focus или перед появлением строки во viewport.

import { preloadFlag } from "@russian-flags/moscow-oblast";

button.addEventListener("pointerenter", () => {
  preloadFlag("balashiha");
});

Неизвестные значения игнорируются и не выбрасывают ошибку.

API

| Экспорт | Описание | | --- | --- | | settlements | Массив метаданных { slug, code, nameRu, nameEn, aliases }. | | settlementSlugs | Массив всех доступных slug. | | normalizeSettlementInput(input) | Нормализует пользовательский ввод перед поиском. | | resolveSettlementSlug(input) | Возвращает slug по slug, коду, названию или alias. | | getFlagModuleLoader(input) | Возвращает ленивый загрузчик модуля флага или undefined. | | loadFlagModule(input) | Лениво импортирует модуль флага. Бросает ошибку для неизвестного значения. | | loadFlagImage(input, options) | Загружает флаг и возвращает HTMLImageElement. | | loadFlag(input, options) | Алиас для loadFlagImage. | | preloadFlag(input) | Запускает загрузку модуля без ожидания результата. | | createFlagImage(src, defaultAlt, options) | Создаёт и настраивает <img> для SVG-флага. |

Типы

Пакет поставляет .d.ts файлы и экспортирует основные типы:

import type {
  FlagImageOptions,
  FlagModule,
  SettlementInput,
  SettlementMeta,
  SettlementSlug,
} from "@russian-flags/moscow-oblast";

FlagImageOptions поддерживает:

| Поле | Назначение | | --- | --- | | alt | Альтернативный текст изображения. | | decoding | Значение свойства HTMLImageElement.decoding. | | loading | Значение свойства HTMLImageElement.loading. | | className | CSS-класс изображения. | | title | Атрибут title. | | id | Атрибут id. | | width, height | Размеры изображения. | | style | Inline-стили. | | dataset | Значения для data-*. | | attributes | Произвольные HTML-атрибуты. |

Совместимость

Пакет рассчитан на современные ESM-проекты и браузерное окружение. Функции loadFlag, loadFlagImage и createFlagImage создают HTMLImageElement, поэтому для них нужен DOM.

Метаданные (settlements, settlementSlugs, resolveSettlementSlug) можно использовать отдельно, например для поиска, автокомплита или генерации списка доступных флагов городов.

Демо

cd examples
npm install
npm run dev

Vite откроет страницу примера в браузере. Пример импортирует опубликованный пакет @russian-flags/moscow-oblast так же, как это будет делать обычное приложение-потребитель.

Разработка

npm install
npm run build
npm test
npm run typecheck
npm run pack:dry

Сборка устроена так:

1. scripts/build-source.js читает src/settlements.ts, проверяет assets/<slug>/index.svg и генерирует TypeScript-исходники.
2. scripts/build.js собирает JavaScript через esbuild и копирует SVG в dist/flags/<slug>.svg.
3. tsc -p tsconfig.build.json генерирует .d.ts файлы в dist.

Чтобы добавить или заменить флаг, положите SVG в assets/<slug>/index.svg и запустите сборку.

Репозиторий

• GitHub: https://github.com/russian-flags/moscow-oblast
• Issues: https://github.com/russian-flags/moscow-oblast/issues

Лицензия

Код пакета распространяется по лицензии MIT. SVG-флаги не входят в MIT-лицензию кода и сохраняют свои исходные лицензии.