@russian-flags/republic-of-crimea

English version

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

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

Превью

| Город | Флаг | slug | | --- | --- | --- | | Алупка | | alupka | | Алушта | | alushta | | Армянск | | armyansk | | Бахчисарай | | bakhchisaray | | Белогорск | | belogorsk | | Джанкой | | dzhankoy | | Евпатория | | evpatoria | | Керчь | | kerch | | Красноперекопск | | krasnoperekopsk | | Саки | | saki | | Симферополь | | simferopol | | Старый Крым | | stary-krym | | Судак | | sudak | | Феодосия | | feodosia | | Щёлкино | | shchyolkino | | Ялта | | yalta |

Возможности

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

Установка

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

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

npm install .

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

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

console.log(settlements[0]);
// {
//   slug: "alupka",
//   code: "ALUPKA",
//   nameRu: "Алупка",
//   nameEn: "Alupka",
//   aliases: [],
// }

const image = await loadFlag("simferopol", {
  alt: "Флаг Симферополя",
  className: "flag",
});

document.body.append(image);

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

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

import simferopolFlag from "@russian-flags/republic-of-crimea/flags/simferopol";
import simferopolSvg from "@russian-flags/republic-of-crimea/svg/simferopol";

console.log(simferopolFlag);
console.log(simferopolSvg);

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

import simferopolFlag from "@russian-flags/republic-of-crimea/flags/simferopol.svg";
import simferopolSvg from "@russian-flags/republic-of-crimea/svg/simferopol.svg";

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

dist/flags/<slug>.svg

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

<img src="https://unpkg.com/@russian-flags/republic-of-crimea/dist/flags/simferopol.svg" alt="Флаг Симферополя" />

Поиск города

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

• slug: "simferopol";
• код: "SIMFEROPOL";
• русское название: "Симферополь";
• английское название: "Simferopol";
• alias: "Shcholkino".

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

console.log(settlements.length); // 16
console.log(settlementSlugs.includes("simferopol")); // true

console.log(resolveSettlementSlug("SIMFEROPOL")); // "simferopol"
console.log(resolveSettlementSlug("Симферополь")); // "simferopol"
console.log(resolveSettlementSlug("STARY_KRYM")); // "stary-krym"
console.log(resolveSettlementSlug("Щёлкино")); // "shchyolkino"
console.log(resolveSettlementSlug("unknown")); // undefined

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

Preload

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

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

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

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

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-флага. |

Типы

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

Демо

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

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

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

Лицензия

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