@russian-flags/republics-of-ussr

@russian-flags/republics-of-ussr

English version

Нативная ESM-коллекция SVG-флагов и метаданных союзных республик СССР для JavaScript и TypeScript. Пакет повторяет устройство других коллекций @russian-flags: отдельные SVG, типизированный список, поиск по названиям и ленивые загрузчики.

Состав основан на странице Wikipedia «Список союзных республик СССР»: 15 республик состава 1956—1991 годов и Карело-Финская ССР как историческая 16-я позиция.

Состав

№	Флаг	Республика	slug	Статус союзной республики
1		Российская СФСР	russian-sfsr	1922—1991
2		Украинская ССР	ukrainian-ssr	1922—1991
3		Белорусская ССР	byelorussian-ssr	1922—1991
4		Узбекская ССР	uzbek-ssr	1925—1991
5		Казахская ССР	kazakh-ssr	1936—1991
6		Грузинская ССР	georgian-ssr	1936—1991
7		Азербайджанская ССР	azerbaijan-ssr	1936—1991
8		Литовская ССР	lithuanian-ssr	1940—1991
9		Молдавская ССР	moldavian-ssr	1940—1991
10		Латвийская ССР	latvian-ssr	1940—1991
11		Киргизская ССР	kirghiz-ssr	1936—1991
12		Таджикская ССР	tajik-ssr	1929—1991
13		Армянская ССР	armenian-ssr	1936—1991
14		Туркменская ССР	turkmen-ssr	1925—1991
15		Эстонская ССР	estonian-ssr	1940—1991
—		Карело-Финская ССР	karelo-finnish-ssr	1940—1956, историческая

Первые 15 элементов расположены в порядке статьи 71 Конституции СССР 1977 года; историческая республика добавлена последней.

Возможности

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

Установка

npm install @russian-flags/republics-of-ussr

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

npm install /path/to/republics-of-USSR

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

import { loadFlag, republics } from "@russian-flags/republics-of-ussr";

console.log(republics[0]);
// {
//   slug: "russian-sfsr",
//   code: "RUSSIAN_SFSR",
//   nameRu: "Российская СФСР",
//   nameEn: "Russian SFSR",
//   fullNameRu: "Российская Советская Федеративная Социалистическая Республика",
//   fullNameEn: "Russian Soviet Federative Socialist Republic",
//   aliases: ["РСФСР", "Россия", "Russia", "RSFSR"],
//   unionFrom: 1922,
//   unionTo: 1991,
//   constitutionalOrder: 1,
//   status: "constituent-1991",
// }

const image = await loadFlag("РСФСР", {
  alt: "Флаг РСФСР",
  className: "flag",
});

document.body.append(image);

loadFlag — alias функции loadFlagImage. Обе функции работают в браузере и требуют глобальный Image/DOM. Метаданные и поиск можно использовать в Node.js.

Прямой импорт SVG

import russianFlag from "@russian-flags/republics-of-ussr/flags/russian-sfsr";
import ukrainianSvg from "@russian-flags/republics-of-ussr/svg/ukrainian-ssr.svg";

console.log(russianFlag);
console.log(ukrainianSvg);

Оба пути указывают на файлы dist/flags/<slug>.svg. Импорт SVG как модуля требует сборщик с поддержкой ассетов, например Vite, webpack или Parcel.

После публикации файлы можно подключать через npm CDN:

<img src="https://unpkg.com/@russian-flags/republics-of-ussr@1.0.1/dist/flags/russian-sfsr.svg" alt="Флаг РСФСР" />

Поиск республики

import {
  normalizeRepublicInput,
  republicSlugs,
  resolveRepublicSlug,
} from "@russian-flags/republics-of-ussr";

console.log(republicSlugs.length); // 16
console.log(resolveRepublicSlug("RUSSIAN_SFSR")); // "russian-sfsr"
console.log(resolveRepublicSlug("РСФСР")); // "russian-sfsr"
console.log(resolveRepublicSlug("Russia")); // "russian-sfsr"
console.log(resolveRepublicSlug("КФССР")); // "karelo-finnish-ssr"
console.log(resolveRepublicSlug("unknown")); // undefined
console.log(normalizeRepublicInput("  UKRAINIAN_SSR ")); // "ukrainian-ssr"

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

API

Экспорт	Описание
republics	Массив метаданных RepublicMeta.
republicSlugs	Массив всех доступных slug.
normalizeRepublicInput(input)	Нормализует пользовательский ввод.
resolveRepublicSlug(input)	Возвращает slug по коду, названию или alias.
getFlagModuleLoader(input)	Возвращает ленивый загрузчик или undefined.
loadFlagModule(input)	Лениво импортирует модуль флага.
loadFlagImage(input, options)	Создаёт HTMLImageElement с флагом.
loadFlag(input, options)	Alias для loadFlagImage.
preloadFlag(input)	Запускает загрузку модуля без ожидания.
createFlagImage(src, defaultAlt, options)	Создаёт и настраивает <img>.

Основные типы: RepublicSlug, RepublicInput, RepublicStatus, RepublicMeta, FlagImageOptions, FlagModule.

Работа с SVG-ассетами

1. Откройте assets/<slug>/index.svg.
2. Внесите изменения в исходный SVG-флаг.
3. Сохраните xmlns="http://www.w3.org/2000/svg" и масштабируемый viewBox.
4. Запустите npm test.

Ассеты в assets являются исходниками пакета. Сборка сама копирует их в dist/flags/<slug>.svg; вручную редактировать dist не нужно.

Демо

npm install
npm --prefix examples install
npm run example:dev

Демо устанавливает @russian-flags/republics-of-ussr из npm, получает список из экспорта republics и лениво загружает каждый SVG через loadFlagModule. Локальная папка assets напрямую не используется.

Разработка

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

scripts/build-source.js читает src/republics.ts, проверяет assets/<slug>/index.svg и генерирует типы и загрузчики. scripts/build.js собирает JavaScript и копирует SVG в dist.

Репозиторий

• GitHub: https://github.com/russian-flags/republics-of-USSR
• Issues: https://github.com/russian-flags/republics-of-USSR/issues

Лицензия

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