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