@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/[email protected]/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.