refactor progress

packages/geo_utils/package.json

@@ -0,0 +1,23 @@
+{
+	"name": "@fluxer/geo_utils",
+	"version": "0.0.0",
+	"private": true,
+	"type": "module",
+	"exports": {
+		"./*": "./*"
+	},
+	"scripts": {
+		"test": "vitest run",
+		"test:watch": "vitest",
+		"typecheck": "tsgo --noEmit"
+	},
+	"dependencies": {
+		"@fluxer/constants": "workspace:*"
+	},
+	"devDependencies": {
+		"@types/node": "catalog:",
+		"@typescript/native-preview": "catalog:",
+		"vite-tsconfig-paths": "catalog:",
+		"vitest": "catalog:"
+	}
+}

packages/geo_utils/src/RegionCodeValidation.tsx

@@ -0,0 +1,50 @@
+/*
+ * Copyright (C) 2026 Fluxer Contributors
+ *
+ * This file is part of Fluxer.
+ *
+ * Fluxer is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Fluxer is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with Fluxer. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+const ASCII_UPPER_A = 65;
+const ASCII_UPPER_Z = 90;
+const REGION_CODE_LENGTH = 2;
+
+function isAsciiUpperAlpha2(value: string): boolean {
+	return (
+		value.length === REGION_CODE_LENGTH &&
+		value.charCodeAt(0) >= ASCII_UPPER_A &&
+		value.charCodeAt(0) <= ASCII_UPPER_Z &&
+		value.charCodeAt(1) >= ASCII_UPPER_A &&
+		value.charCodeAt(1) <= ASCII_UPPER_Z
+	);
+}
+
+export function normalizeRegionCode(regionCode: string): string | undefined {
+	const trimmedRegionCode = regionCode.trim();
+	if (trimmedRegionCode.length !== REGION_CODE_LENGTH) {
+		return undefined;
+	}
+
+	const upperRegionCode = trimmedRegionCode.toUpperCase();
+	if (!isAsciiUpperAlpha2(upperRegionCode)) {
+		return undefined;
+	}
+
+	return upperRegionCode;
+}
+
+export function isRegionCode(value: string): boolean {
+	return normalizeRegionCode(value) !== undefined;
+}

packages/geo_utils/src/RegionDisplayNameResolver.tsx

@@ -0,0 +1,75 @@
+/*
+ * Copyright (C) 2026 Fluxer Contributors
+ *
+ * This file is part of Fluxer.
+ *
+ * Fluxer is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Fluxer is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with Fluxer. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import {Locales} from '@fluxer/constants/src/Locales';
+import {normalizeRegionCode} from '@fluxer/geo_utils/src/RegionCodeValidation';
+
+const DISPLAY_NAME_TYPE: Intl.DisplayNamesOptions['type'] = 'region';
+const DISPLAY_NAME_FALLBACK: Intl.DisplayNamesOptions['fallback'] = 'none';
+
+const displayNamesByLocale = new Map<string, Intl.DisplayNames>();
+
+function resolveLocale(locale?: string): string {
+	const trimmedLocale = locale?.trim();
+	if (trimmedLocale && trimmedLocale.length > 0) {
+		return trimmedLocale;
+	}
+
+	return Locales.EN_US;
+}
+
+function getDisplayNames(locale?: string): Intl.DisplayNames {
+	const localeCode = resolveLocale(locale);
+	const cachedDisplayNames = displayNamesByLocale.get(localeCode);
+	if (cachedDisplayNames) {
+		return cachedDisplayNames;
+	}
+
+	const displayNames = new Intl.DisplayNames([localeCode], {
+		type: DISPLAY_NAME_TYPE,
+		fallback: DISPLAY_NAME_FALLBACK,
+	});
+	displayNamesByLocale.set(localeCode, displayNames);
+	return displayNames;
+}
+
+function resolveRegionDisplayNameFromFormatter(
+	regionCode: string,
+	displayNames: Intl.DisplayNames,
+): string | undefined {
+	const normalizedRegionCode = normalizeRegionCode(regionCode);
+	if (!normalizedRegionCode) {
+		return undefined;
+	}
+
+	return displayNames.of(normalizedRegionCode) ?? undefined;
+}
+
+export function resolveRegionDisplayName(regionCode: string, locale?: string): string | undefined {
+	const displayNames = getDisplayNames(locale);
+	return resolveRegionDisplayNameFromFormatter(regionCode, displayNames);
+}
+
+export function resolveRegionDisplayNames(
+	regionCodes: ReadonlyArray<string>,
+	locale?: string,
+): Array<string | undefined> {
+	const displayNames = getDisplayNames(locale);
+	return regionCodes.map((regionCode) => resolveRegionDisplayNameFromFormatter(regionCode, displayNames));
+}

packages/geo_utils/src/RegionFormatting.tsx

@@ -0,0 +1,64 @@
+/*
+ * Copyright (C) 2026 Fluxer Contributors
+ *
+ * This file is part of Fluxer.
+ *
+ * Fluxer is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Fluxer is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with Fluxer. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import {normalizeRegionCode} from '@fluxer/geo_utils/src/RegionCodeValidation';
+import {resolveRegionDisplayName, resolveRegionDisplayNames} from '@fluxer/geo_utils/src/RegionDisplayNameResolver';
+
+export interface RegionDisplayNameOptions {
+	locale?: string;
+	fallbackToRegionCode?: boolean;
+}
+
+function applyRegionCodeFallback(
+	regionCode: string,
+	displayName: string | undefined,
+	options?: RegionDisplayNameOptions,
+): string | undefined {
+	if (displayName) {
+		return displayName;
+	}
+	if (!options?.fallbackToRegionCode) {
+		return undefined;
+	}
+
+	const normalizedRegionCode = normalizeRegionCode(regionCode);
+	if (normalizedRegionCode) {
+		return normalizedRegionCode;
+	}
+
+	const trimmedRegionCode = regionCode.trim();
+	return trimmedRegionCode.length > 0 ? trimmedRegionCode : undefined;
+}
+
+export function getRegionDisplayName(regionCode: string, options?: RegionDisplayNameOptions): string | undefined {
+	const displayName = resolveRegionDisplayName(regionCode, options?.locale);
+	return applyRegionCodeFallback(regionCode, displayName, options);
+}
+
+export function getRegionDisplayNames(
+	regionCodes: ReadonlyArray<string>,
+	options?: RegionDisplayNameOptions,
+): Array<string | undefined> {
+	const displayNames = resolveRegionDisplayNames(regionCodes, options?.locale);
+
+	return displayNames.map((displayName, index) => {
+		const regionCode = regionCodes[index] ?? '';
+		return applyRegionCodeFallback(regionCode, displayName, options);
+	});
+}

packages/geo_utils/src/__tests__/RegionCodeValidation.test.tsx

@@ -0,0 +1,82 @@
+/*
+ * Copyright (C) 2026 Fluxer Contributors
+ *
+ * This file is part of Fluxer.
+ *
+ * Fluxer is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Fluxer is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with Fluxer. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import {isRegionCode, normalizeRegionCode} from '@fluxer/geo_utils/src/RegionCodeValidation';
+import {describe, expect, it} from 'vitest';
+
+describe('normalizeRegionCode', () => {
+	it('returns uppercase for valid lowercase codes', () => {
+		expect(normalizeRegionCode('us')).toBe('US');
+		expect(normalizeRegionCode('gb')).toBe('GB');
+		expect(normalizeRegionCode('fr')).toBe('FR');
+	});
+
+	it('returns uppercase for already uppercase codes', () => {
+		expect(normalizeRegionCode('US')).toBe('US');
+		expect(normalizeRegionCode('DE')).toBe('DE');
+	});
+
+	it('handles mixed case', () => {
+		expect(normalizeRegionCode('Us')).toBe('US');
+		expect(normalizeRegionCode('gB')).toBe('GB');
+	});
+
+	it('trims whitespace', () => {
+		expect(normalizeRegionCode(' US ')).toBe('US');
+		expect(normalizeRegionCode('\tFR\n')).toBe('FR');
+	});
+
+	it('returns undefined for empty string', () => {
+		expect(normalizeRegionCode('')).toBeUndefined();
+	});
+
+	it('returns undefined for single character', () => {
+		expect(normalizeRegionCode('U')).toBeUndefined();
+	});
+
+	it('returns undefined for three or more characters', () => {
+		expect(normalizeRegionCode('USA')).toBeUndefined();
+		expect(normalizeRegionCode('ABCD')).toBeUndefined();
+	});
+
+	it('returns undefined for non-alpha characters', () => {
+		expect(normalizeRegionCode('12')).toBeUndefined();
+		expect(normalizeRegionCode('A1')).toBeUndefined();
+		expect(normalizeRegionCode('!@')).toBeUndefined();
+	});
+
+	it('returns undefined for whitespace-only input', () => {
+		expect(normalizeRegionCode('   ')).toBeUndefined();
+	});
+});
+
+describe('isRegionCode', () => {
+	it('returns true for valid region codes', () => {
+		expect(isRegionCode('US')).toBe(true);
+		expect(isRegionCode('gb')).toBe(true);
+		expect(isRegionCode(' FR ')).toBe(true);
+	});
+
+	it('returns false for invalid values', () => {
+		expect(isRegionCode('')).toBe(false);
+		expect(isRegionCode('USA')).toBe(false);
+		expect(isRegionCode('1')).toBe(false);
+		expect(isRegionCode('12')).toBe(false);
+	});
+});

packages/geo_utils/src/__tests__/RegionDisplayNameResolver.test.tsx

@@ -0,0 +1,70 @@
+/*
+ * Copyright (C) 2026 Fluxer Contributors
+ *
+ * This file is part of Fluxer.
+ *
+ * Fluxer is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Fluxer is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with Fluxer. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import {resolveRegionDisplayName, resolveRegionDisplayNames} from '@fluxer/geo_utils/src/RegionDisplayNameResolver';
+import {describe, expect, it} from 'vitest';
+
+describe('resolveRegionDisplayName', () => {
+	it('resolves known region codes to display names', () => {
+		expect(resolveRegionDisplayName('US')).toBe('United States');
+		expect(resolveRegionDisplayName('GB')).toBe('United Kingdom');
+		expect(resolveRegionDisplayName('FR')).toBe('France');
+	});
+
+	it('resolves lowercase region codes', () => {
+		expect(resolveRegionDisplayName('us')).toBe('United States');
+		expect(resolveRegionDisplayName('de')).toBe('Germany');
+	});
+
+	it('returns undefined for invalid codes', () => {
+		expect(resolveRegionDisplayName('XX')).toBeUndefined();
+		expect(resolveRegionDisplayName('')).toBeUndefined();
+		expect(resolveRegionDisplayName('USA')).toBeUndefined();
+	});
+
+	it('respects locale parameter', () => {
+		const frenchName = resolveRegionDisplayName('DE', 'fr');
+		expect(frenchName).toBe('Allemagne');
+	});
+
+	it('defaults to en-US when no locale provided', () => {
+		expect(resolveRegionDisplayName('JP')).toBe('Japan');
+	});
+});
+
+describe('resolveRegionDisplayNames', () => {
+	it('resolves multiple region codes', () => {
+		const result = resolveRegionDisplayNames(['US', 'GB', 'FR']);
+		expect(result).toEqual(['United States', 'United Kingdom', 'France']);
+	});
+
+	it('returns undefined for invalid entries in the array', () => {
+		const result = resolveRegionDisplayNames(['US', 'XX', 'FR']);
+		expect(result).toEqual(['United States', undefined, 'France']);
+	});
+
+	it('returns empty array for empty input', () => {
+		expect(resolveRegionDisplayNames([])).toEqual([]);
+	});
+
+	it('respects locale for all entries', () => {
+		const result = resolveRegionDisplayNames(['US', 'DE'], 'fr');
+		expect(result).toEqual(['États-Unis', 'Allemagne']);
+	});
+});

packages/geo_utils/src/__tests__/RegionFormatting.test.tsx

@@ -0,0 +1,82 @@
+/*
+ * Copyright (C) 2026 Fluxer Contributors
+ *
+ * This file is part of Fluxer.
+ *
+ * Fluxer is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Fluxer is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with Fluxer. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import {getRegionDisplayName, getRegionDisplayNames} from '@fluxer/geo_utils/src/RegionFormatting';
+import {describe, expect, it} from 'vitest';
+
+describe('getRegionDisplayName', () => {
+	it('returns display name for valid region code', () => {
+		expect(getRegionDisplayName('US')).toBe('United States');
+		expect(getRegionDisplayName('GB')).toBe('United Kingdom');
+	});
+
+	it('returns undefined for unknown region code without fallback', () => {
+		expect(getRegionDisplayName('XX')).toBeUndefined();
+	});
+
+	it('returns region code when fallbackToRegionCode is enabled', () => {
+		expect(getRegionDisplayName('XX', {fallbackToRegionCode: true})).toBe('XX');
+	});
+
+	it('normalizes and returns fallback for lowercase unknown codes', () => {
+		expect(getRegionDisplayName('xx', {fallbackToRegionCode: true})).toBe('XX');
+	});
+
+	it('returns undefined for empty string even with fallback', () => {
+		expect(getRegionDisplayName('', {fallbackToRegionCode: true})).toBeUndefined();
+	});
+
+	it('returns undefined for whitespace-only even with fallback', () => {
+		expect(getRegionDisplayName('   ', {fallbackToRegionCode: true})).toBeUndefined();
+	});
+
+	it('respects locale option', () => {
+		expect(getRegionDisplayName('DE', {locale: 'fr'})).toBe('Allemagne');
+	});
+
+	it('uses en-US by default', () => {
+		expect(getRegionDisplayName('JP')).toBe('Japan');
+	});
+});
+
+describe('getRegionDisplayNames', () => {
+	it('returns display names for multiple valid codes', () => {
+		const result = getRegionDisplayNames(['US', 'FR', 'DE']);
+		expect(result).toEqual(['United States', 'France', 'Germany']);
+	});
+
+	it('returns undefined for invalid codes without fallback', () => {
+		const result = getRegionDisplayNames(['US', 'XX']);
+		expect(result).toEqual(['United States', undefined]);
+	});
+
+	it('returns fallback codes when enabled', () => {
+		const result = getRegionDisplayNames(['US', 'XX'], {fallbackToRegionCode: true});
+		expect(result).toEqual(['United States', 'XX']);
+	});
+
+	it('respects locale for all entries', () => {
+		const result = getRegionDisplayNames(['US', 'DE'], {locale: 'fr'});
+		expect(result).toEqual(['États-Unis', 'Allemagne']);
+	});
+
+	it('returns empty array for empty input', () => {
+		expect(getRegionDisplayNames([])).toEqual([]);
+	});
+});

packages/geo_utils/tsconfig.json

@@ -0,0 +1,5 @@
+{
+	"extends": "../../tsconfigs/package.json",
+	"compilerOptions": {},
+	"include": ["src/**/*"]
+}

packages/geo_utils/vitest.config.ts

@@ -0,0 +1,44 @@
+/*
+ * Copyright (C) 2026 Fluxer Contributors
+ *
+ * This file is part of Fluxer.
+ *
+ * Fluxer is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Fluxer is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with Fluxer. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import tsconfigPaths from 'vite-tsconfig-paths';
+import {defineConfig} from 'vitest/config';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export default defineConfig({
+	plugins: [
+		tsconfigPaths({
+			root: path.resolve(__dirname, '../..'),
+		}),
+	],
+	test: {
+		globals: true,
+		environment: 'node',
+		include: ['**/*.{test,spec}.{ts,tsx}'],
+		exclude: ['node_modules', 'dist'],
+		coverage: {
+			provider: 'v8',
+			reporter: ['text', 'json', 'html'],
+			exclude: ['**/*.test.tsx', '**/*.spec.tsx', 'node_modules/'],
+		},
+	},
+});