@russian-flags/arkhangelsk-oblast

English version

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

Список основан на странице Wikipedia "Городские населённые пункты Архангельской области", раздел "Города": 13 городов. Посёлки городского типа не включены.

Превью

Город	Флаг	slug
Архангельск		arkhangelsk
Северодвинск		severodvinsk
Котлас		kotlas
Новодвинск		novodvinsk
Коряжма		koryazhma
Мирный		mirnyy
Вельск		velsk
Няндома		nyandoma
Онега		onega
Каргополь		kargopol
Шенкурск		shenkursk
Мезень		mezen
Сольвычегодск		solvychegodsk

Возможности

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

Установка

npm install @russian-flags/arkhangelsk-oblast

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

npm install .

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

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

console.log(settlements[0]);
// {
//   slug: "arkhangelsk",
//   code: "ARKHANGELSK",
//   nameRu: "Архангельск",
//   nameEn: "Arkhangelsk",
//   aliases: ["Archangelsk", "Arkhangel'sk"],
// }

const image = await loadFlag("arkhangelsk", {
  alt: "Флаг Архангельска",
  className: "flag",
});

document.body.append(image);

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

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

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

import arkhangelskFlag from "@russian-flags/arkhangelsk-oblast/flags/arkhangelsk";
import arkhangelskSvg from "@russian-flags/arkhangelsk-oblast/svg/arkhangelsk";

console.log(arkhangelskFlag);
console.log(arkhangelskSvg);

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

import arkhangelskFlag from "@russian-flags/arkhangelsk-oblast/flags/arkhangelsk.svg";
import arkhangelskSvg from "@russian-flags/arkhangelsk-oblast/svg/arkhangelsk.svg";

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

dist/flags/<slug>.svg

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

<img src="https://unpkg.com/@russian-flags/arkhangelsk-oblast/dist/flags/arkhangelsk.svg" alt="Флаг Архангельска"/>

Поиск города

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

• slug: "arkhangelsk";
• код: "ARKHANGELSK";
• русское название: "Архангельск";
• английское название: "Arkhangelsk";
• alias: "Archangelsk".

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

console.log(settlements.length); // 13
console.log(settlementSlugs.includes("arkhangelsk")); // true

console.log(resolveSettlementSlug("ARKHANGELSK")); // "arkhangelsk"
console.log(resolveSettlementSlug("Архангельск")); // "arkhangelsk"
console.log(resolveSettlementSlug("Arkhangelsk")); // "arkhangelsk"
console.log(resolveSettlementSlug("Archangelsk")); // "arkhangelsk"
console.log(resolveSettlementSlug("unknown")); // undefined

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

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

import { loadFlag, settlements } from "@russian-flags/arkhangelsk-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/arkhangelsk-oblast";

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

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

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/arkhangelsk-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 откроет страницу примера в браузере.

Разработка

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.

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

Репозиторий

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

Лицензия

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