@russian-flags/republic-of-tatarstan

English version

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

Список основан на странице Wikipedia "Городские населённые пункты Татарстана", раздел "Города": 24 города. Посёлки городского типа не включены.

Коллекция содержит 24 готовых оптимизированных SVG-флага. Исходные файлы проекта находятся в assets/<slug>/index.svg, а при сборке их копии попадают в dist/flags/<slug>.svg.

Превью

Город	Флаг	slug
Агрыз		agryz
Азнакаево		aznakayevo
Альметьевск		almetyevsk
Арск		arsk
Бавлы		bavly
Болгар		bolgar
Бугульма		bugulma
Буинск		buinsk
Елабуга		yelabuga
Заинск		zainsk
Зеленодольск		zelenodolsk
Иннополис		innopolis
Казань		kazan
Кукмор		kukmor
Лаишево		laishevo
Лениногорск		leninogorsk
Мамадыш		mamadysh
Менделеевск		mendeleyevsk
Мензелинск		menzelinsk
Набережные Челны		naberezhnye-chelny
Нижнекамск		nizhnekamsk
Нурлат		nurlat
Тетюши		tetyushi
Чистополь		chistopol

Возможности

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

Установка

npm install @russian-flags/republic-of-tatarstan

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

npm install /path/to/republic-of-tatarstan

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

import { loadFlag, settlements } from "@russian-flags/republic-of-tatarstan";

console.log(settlements[0]);
// {
//   slug: "agryz",
//   code: "AGRYZ",
//   nameRu: "Агрыз",
//   nameEn: "Agryz",
//   aliases: ["Әгерҗе"],
// }

const image = await loadFlag("kazan", {
  alt: "Флаг Казани",
  className: "flag",
});

document.body.append(image);

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

API создания изображений (loadFlag, loadFlagImage, createFlagImage) рассчитан на браузер и требует глобальный Image/DOM. Метаданные и функции поиска можно использовать в Node.js без DOM.

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

import kazanFlag from "@russian-flags/republic-of-tatarstan/flags/kazan";
import kazanSvg from "@russian-flags/republic-of-tatarstan/svg/kazan";

console.log(kazanFlag);
console.log(kazanSvg);

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

import kazanFlag from "@russian-flags/republic-of-tatarstan/flags/kazan.svg";
import kazanSvg from "@russian-flags/republic-of-tatarstan/svg/kazan.svg";

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

dist/flags/<slug>.svg

Default-импорт SVG возвращает URL-строку и требует сборщик с поддержкой SVG-ассетов, например Vite, webpack или Parcel. Нативный Node.js не импортирует .svg как JavaScript-модуль; для него используйте метаданные пакета или обычный путь к файлу.

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

<img src="https://unpkg.com/@russian-flags/republic-of-tatarstan@1.0.0/dist/flags/kazan.svg" alt="Флаг Казани" />

Поиск города

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

• slug: "kazan";
• код: "KAZAN";
• русское название: "Казань";
• английское название: "Kazan";
• alias: "Казан".

import {
  resolveSettlementSlug,
  settlementSlugs,
  settlements,
} from "@russian-flags/republic-of-tatarstan";

console.log(settlements.length); // 24
console.log(settlementSlugs.includes("kazan")); // true

console.log(resolveSettlementSlug("KAZAN")); // "kazan"
console.log(resolveSettlementSlug("Казань")); // "kazan"
console.log(resolveSettlementSlug("Казан")); // "kazan"
console.log(resolveSettlementSlug("NABEREZHNYE_CHELNY")); // "naberezhnye-chelny"
console.log(resolveSettlementSlug("Яр Чаллы")); // "naberezhnye-chelny"
console.log(resolveSettlementSlug("unknown")); // undefined

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

Preload

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

import { preloadFlag } from "@russian-flags/republic-of-tatarstan";

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

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

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; отклоняет Promise для неизвестного значения.
loadFlag(input, options)	Алиас для loadFlagImage с тем же поведением.
preloadFlag(input)	Запускает загрузку модуля без ожидания результата.
createFlagImage(src, defaultAlt, options)	Создаёт и настраивает <img> для SVG-флага.

Типы

import type {
  FlagImageOptions,
  FlagImageAttributeValue,
  FlagImageFactory,
  FlagModule,
  SettlementInput,
  SettlementMeta,
  SettlementSlug,
} from "@russian-flags/republic-of-tatarstan";

Демо

cd examples
npm install
npm run dev

Vite откроет страницу примера в браузере. В отличие от npm API пакета, пример отображает SVG напрямую из assets.

Разработка

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

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

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/republic-of-tatarstan
• Issues: https://github.com/russian-flags/republic-of-tatarstan/issues

Лицензия

Код пакета распространяется по лицензии MIT. SVG-флаги изображают официальные муниципальные символы и не лицензируются этим пакетом на условиях MIT. Использование названий, эмблем и официальных символов может регулироваться отдельно; подробности см. в LICENSE.