@russian-flags/regions-react

English version

React-обертка над @russian-flags/regions. Пакет можно использовать в React-проектах как набор готовых компонентов флагов регионов России, lazy-компонент по коду региона и тонкие entry-point'ы поверх SVG-ассетов базового пакета.

Пакет содержит 89 регионов: республики, края, области, города федерального значения, автономную область и автономные округа.

Превью

| Регион | Код | ISO-код | Автокод | Флаг | | --- | --- | --- | --- | --- | | Санкт-Петербург | SPE | RU-SPE | 78 | | | Москва | MOW | RU-MOW | 77 | | | Севастополь | SEV | RU-SEV | 92, 93 | | | Новосибирская область | NVS | RU-NVS | 54 | |

Возможности

• React-компоненты для прямого импорта каждого флага.
• Lazy-компонент RegionFlag для отображения флага по коду, ISO-коду, автокоду, названию или алиасу.
• ESM-сборка с TypeScript-типами.
• Метаданные и поиск регионов реэкспортируются из @russian-flags/regions.
• SVG не дублируются в React-пакете: компоненты используют ассеты базового пакета.
• Compatibility entry-point'ы для SVG URL через svg/<CODE>.svg.

Установка

npm install @russian-flags/regions-react react

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

npm install .

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

import { RegionFlag, regions } from "@russian-flags/regions-react";

export function App() {
  console.log(regions[0]);
  // {
  //   code: "AD",
  //   isoCode: "RU-AD",
  //   nameRu: "Республика Адыгея",
  //   nameEn: "Republic of Adygea",
  //   numericCodes: [1],
  //   aliases: ["ADYGEA", "АДЫГЕЯ"]
  // }

  return (
    <RegionFlag
      code="TA"
      width={96}
      alt="Флаг Республики Татарстан"
      loadingFallback={null}
    />
  );
}

RegionFlag нормализует входное значение через справочник @russian-flags/regions, лениво импортирует нужный React-компонент и по умолчанию ставит для изображения loading="lazy" и decoding="async".

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

Если регион известен на этапе разработки, импортируйте компонент напрямую. Entry-point'ы компонентов сделаны в нижнем регистре:

import TatarstanFlag from "@russian-flags/regions-react/flags/ta";

export function Example() {
  return <TatarstanFlag width={48} />;
}

Так в приложение попадает только маленький JS-модуль конкретного React-компонента и SVG из @russian-flags/regions. Остальные компоненты флагов не импортируются.

Каждый модуль флага также экспортирует regionCode и src:

import TatarstanFlag, { regionCode, src } from "@russian-flags/regions-react/flags/ta";

console.log(regionCode); // "TA"
console.log(src); // URL SVG-ассета

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

Если нужен только URL SVG, лучше импортировать ассет из базового пакета:

import tatarstanSvg from "@russian-flags/regions/svg/ta.svg";

export function Example() {
  return <img src={tatarstanSvg} width={48} alt="Флаг Республики Татарстан" />;
}

React-пакет также оставляет compatibility entry-point'ы для импортов с кодом в верхнем регистре:

import tatarstanSvg from "@russian-flags/regions-react/svg/TA.svg";

Эти entry-point'ы не содержат локальных SVG-файлов и реэкспортируют URL из @russian-flags/regions.

Поиск региона

RegionFlag, loadRegionFlag, preloadRegionFlag и метаданные принимают те же значения, что и базовый пакет:

• короткий код: "TA";
• ISO-код: "RU-TA";
• автомобильный код: 16, "16" или "016";
• русское или английское название;
• алиас из справочника, например "TATARSTAN".

import {
  getRegionMeta,
  regionCodes,
  regions,
  resolveRegionCode,
} from "@russian-flags/regions-react";

console.log(regions.length); // 89
console.log(regionCodes.includes("TA")); // true

console.log(resolveRegionCode("RU-TA")); // "TA"
console.log(resolveRegionCode(16)); // "TA"
console.log(resolveRegionCode("tatarstan")); // "TA"
console.log(resolveRegionCode("Республика Татарстан")); // "TA"
console.log(resolveRegionCode("unknown")); // undefined

console.log(getRegionMeta("RU-TA")?.nameRu); // "Республика Татарстан"

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

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

import { RegionFlag, regions } from "@russian-flags/regions-react";

export function RegionList() {
  return (
    <ul>
      {regions.map((region) => (
        <li key={region.code}>
          <RegionFlag code={region.code} width={32} loadingFallback={null} />
          <span>{region.nameRu}</span>
        </li>
      ))}
    </ul>
  );
}

RegionFlag использует React.lazy и Suspense, поэтому каждый флаг загружается через динамический импорт своего компонента.

Preload

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

import { preloadRegionFlag } from "@russian-flags/regions-react";

button.addEventListener("pointerenter", () => {
  preloadRegionFlag("TA");
});

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

API

| Экспорт | Описание | | --- | --- | | RegionFlag | Lazy React-компонент для отображения флага по коду региона. | | flagLoaders | Таблица ленивых загрузчиков React-компонентов по короткому коду региона. | | getRegionFlagLoader(input) | Возвращает lazy-loader React-компонента флага или undefined. | | loadRegionFlag(input) | Лениво импортирует React-модуль флага. Бросает ошибку для неизвестного значения. | | preloadRegionFlag(input) | Запускает загрузку React-модуля без ожидания результата. | | regions | Массив метаданных { code, isoCode, nameRu, nameEn, numericCodes, aliases }. | | regionCodes | Массив всех доступных коротких кодов регионов. | | normalizeRegionCode(input) | Нормализует пользовательский ввод перед поиском. | | resolveRegionCode(input) | Возвращает короткий код региона по коду, ISO-коду, номеру, названию или алиасу. | | isRegionCode(input) | Type guard для канонического RegionCode. | | getRegionMeta(input) | Возвращает метаданные региона или undefined. |

Entry-point'ы

| Entry-point | Назначение | | --- | --- | | @russian-flags/regions-react | Основной API: React-компонент, загрузчики, метаданные и типы. | | @russian-flags/regions-react/dynamic | Только динамические загрузчики React-компонентов. | | @russian-flags/regions-react/meta | Метаданные и функции поиска, реэкспортированные из @russian-flags/regions. | | @russian-flags/regions-react/regions | Только массив regions. | | @russian-flags/regions-react/region-flag | Только компонент RegionFlag. | | @russian-flags/regions-react/flags/<code> | Прямой импорт React-компонента флага. | | @russian-flags/regions-react/svg/<CODE>.svg | Compatibility импорт URL SVG из базового пакета. |

Типы

Пакет поставляет .d.ts файлы и экспортирует основные типы:

import type {
  IDynamicRegionFlagProps,
  IRegionFlagModule,
  IRegionMeta,
  RegionCode,
  RegionFlagComponent,
  RegionFlagProps,
  RegionInput,
  RegionMeta,
} from "@russian-flags/regions-react";

RegionFlagProps основан на ImgHTMLAttributes<HTMLImageElement>, но исключает src: источник SVG выбирает сам компонент.

IDynamicRegionFlagProps добавляет поля:

| Поле | Назначение | | --- | --- | | code | Код, ISO-код, автокод, название или алиас региона. | | fallback | React-узел для неизвестного значения. | | loadingFallback | React-узел, который отображается во время lazy-загрузки. |

Совместимость

Пакет рассчитан на React 18+, современные ESM-проекты и сборщики, которые поддерживают package exports и импорт SVG как URL.

React-компоненты можно использовать только в React-окружении. Метаданные (regions, regionCodes, resolveRegionCode, getRegionMeta) можно использовать отдельно, например для поиска, автокомплита или генерации списка доступных флагов.

Демо

cd examples/vite-react
npm install
npm run dev

Vite откроет страницу примера в браузере. Пример устанавливает React-пакет из корня репозитория через file:../.. и использует SVG-ассеты из @russian-flags/regions.

Разработка

npm install
npm run build
npm test
npm run typecheck
npm pack --dry-run

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

1. scripts/build.mjs собирает TypeScript и TSX через esbuild.
2. tsc --emitDeclarationOnly генерирует .d.ts файлы в dist.
3. src/svg/*.svg.ts собираются в маленькие JS-модули, которые реэкспортят SVG URL из @russian-flags/regions.

Чтобы обновить набор регионов, сначала обновите базовый пакет @russian-flags/regions, затем синхронизируйте React-компоненты и wrapper entry-point'ы с его regionCodes.

Репозиторий

• GitHub: https://github.com/russian-flags/regions-react
• Issues: https://github.com/russian-flags/regions-react/issues
• Базовый пакет: https://github.com/russian-flags/regions

Лицензия

Код пакета распространяется по лицензии MIT. SVG-флаги поставляются базовым пакетом @russian-flags/regions и сохраняют свои исходные лицензии.