meno-core 1.0.0

package/lib/shared/i18n.test.ts

@@ -0,0 +1,313 @@
+import { describe, test, expect } from 'bun:test';
+import {
+  DEFAULT_I18N_CONFIG,
+  getLocaleCodes,
+  findLocaleByCode,
+  isValidLocaleCode,
+  migrateI18nConfig,
+  isI18nValue,
+  resolveTranslation,
+  resolveI18nValue,
+  resolveI18nInProps,
+  extractLocaleFromPath,
+  buildLocalizedPath,
+  parseLocaleFromPath,
+} from './i18n';
+import type { I18nConfig, I18nValue } from './types/components';
+
+describe('i18n', () => {
+  const testConfig: I18nConfig = {
+    defaultLocale: 'en',
+    locales: [
+      { code: 'en', name: 'English', nativeName: 'English', langTag: 'en-US' },
+      { code: 'pl', name: 'Polish', nativeName: 'Polski', langTag: 'pl-PL' },
+      { code: 'de', name: 'German', nativeName: 'Deutsch', langTag: 'de-DE' },
+    ],
+  };
+
+  describe('DEFAULT_I18N_CONFIG', () => {
+    test('should have default locale en', () => {
+      expect(DEFAULT_I18N_CONFIG.defaultLocale).toBe('en');
+    });
+
+    test('should have English locale configured', () => {
+      expect(DEFAULT_I18N_CONFIG.locales).toHaveLength(1);
+      expect(DEFAULT_I18N_CONFIG.locales[0].code).toBe('en');
+    });
+  });
+
+  describe('getLocaleCodes', () => {
+    test('should extract locale codes from config', () => {
+      const codes = getLocaleCodes(testConfig);
+      expect(codes).toEqual(['en', 'pl', 'de']);
+    });
+
+    test('should handle empty locales array', () => {
+      const config: I18nConfig = { defaultLocale: 'en', locales: [] };
+      expect(getLocaleCodes(config)).toEqual([]);
+    });
+  });
+
+  describe('findLocaleByCode', () => {
+    test('should find locale by code', () => {
+      const locale = findLocaleByCode(testConfig, 'pl');
+      expect(locale?.code).toBe('pl');
+      expect(locale?.nativeName).toBe('Polski');
+    });
+
+    test('should return undefined for non-existent code', () => {
+      expect(findLocaleByCode(testConfig, 'fr')).toBeUndefined();
+    });
+  });
+
+  describe('isValidLocaleCode', () => {
+    test('should return true for valid codes', () => {
+      expect(isValidLocaleCode(testConfig, 'en')).toBe(true);
+      expect(isValidLocaleCode(testConfig, 'pl')).toBe(true);
+      expect(isValidLocaleCode(testConfig, 'de')).toBe(true);
+    });
+
+    test('should return false for invalid codes', () => {
+      expect(isValidLocaleCode(testConfig, 'fr')).toBe(false);
+      expect(isValidLocaleCode(testConfig, 'es')).toBe(false);
+    });
+  });
+
+  describe('migrateI18nConfig', () => {
+    test('should migrate old string array format', () => {
+      const oldConfig = {
+        defaultLocale: 'en',
+        locales: ['en', 'pl', 'de'],
+      };
+
+      const migrated = migrateI18nConfig(oldConfig);
+      expect(migrated.defaultLocale).toBe('en');
+      expect(migrated.locales).toHaveLength(3);
+      expect(migrated.locales[0].code).toBe('en');
+      expect(migrated.locales[1].code).toBe('pl');
+    });
+
+    test('should preserve new format config', () => {
+      const migrated = migrateI18nConfig(testConfig);
+      expect(migrated).toEqual(testConfig);
+    });
+
+    test('should return default config for invalid input', () => {
+      expect(migrateI18nConfig(null)).toEqual(DEFAULT_I18N_CONFIG);
+      expect(migrateI18nConfig(undefined)).toEqual(DEFAULT_I18N_CONFIG);
+      expect(migrateI18nConfig('invalid')).toEqual(DEFAULT_I18N_CONFIG);
+    });
+
+    test('should return default config for missing locales', () => {
+      const invalidConfig = { defaultLocale: 'en' };
+      expect(migrateI18nConfig(invalidConfig)).toEqual(DEFAULT_I18N_CONFIG);
+    });
+  });
+
+  describe('isI18nValue', () => {
+    test('should return true for valid I18nValue', () => {
+      const value: I18nValue = {
+        _i18n: true,
+        en: 'Hello',
+        pl: 'Cze[',
+      };
+      expect(isI18nValue(value)).toBe(true);
+    });
+
+    test('should return false for regular objects', () => {
+      expect(isI18nValue({ text: 'Hello' })).toBe(false);
+      expect(isI18nValue({ en: 'Hello' })).toBe(false);
+    });
+
+    test('should return false for non-objects', () => {
+      expect(isI18nValue(null)).toBe(false);
+      expect(isI18nValue(undefined)).toBe(false);
+      expect(isI18nValue('string')).toBe(false);
+      expect(isI18nValue(123)).toBe(false);
+      expect(isI18nValue([])).toBe(false);
+    });
+  });
+
+  describe('resolveTranslation', () => {
+    const i18nValue: I18nValue = {
+      _i18n: true,
+      en: 'Hello',
+      pl: 'Cze[',
+      de: 'Hallo',
+    };
+
+    test('should resolve exact locale match', () => {
+      expect(resolveTranslation(i18nValue, 'pl', testConfig)).toBe('Cze[');
+      expect(resolveTranslation(i18nValue, 'de', testConfig)).toBe('Hallo');
+    });
+
+    test('should fallback to default locale', () => {
+      const value: I18nValue = {
+        _i18n: true,
+        en: 'Hello',
+        pl: 'Cze[',
+      };
+      expect(resolveTranslation(value, 'fr', testConfig)).toBe('Hello');
+    });
+
+    test('should fallback to first available translation', () => {
+      const value: I18nValue = {
+        _i18n: true,
+        pl: 'Cze[',
+      };
+      expect(resolveTranslation(value, 'fr', testConfig)).toBe('Cze[');
+    });
+
+    test('should return empty string if no translation available', () => {
+      const value: I18nValue = { _i18n: true };
+      expect(resolveTranslation(value, 'en', testConfig)).toBe('');
+    });
+  });
+
+  describe('resolveI18nValue', () => {
+    test('should resolve I18nValue', () => {
+      const value: I18nValue = {
+        _i18n: true,
+        en: 'Hello',
+        pl: 'Cze[',
+      };
+      expect(resolveI18nValue(value, 'pl', testConfig)).toBe('Cze[');
+    });
+
+    test('should return non-I18nValue unchanged', () => {
+      expect(resolveI18nValue('Hello', 'pl', testConfig)).toBe('Hello');
+      expect(resolveI18nValue(123, 'pl', testConfig)).toBe(123);
+      expect(resolveI18nValue(null, 'pl', testConfig)).toBeNull();
+    });
+  });
+
+  describe('resolveI18nInProps', () => {
+    test('should resolve I18nValue props', () => {
+      const props = {
+        title: { _i18n: true, en: 'Hello', pl: 'Cze[' },
+        count: 5,
+      };
+
+      const resolved = resolveI18nInProps(props, 'pl', testConfig);
+      expect(resolved.title).toBe('Cze[');
+      expect(resolved.count).toBe(5);
+    });
+
+    test('should resolve I18nValue in arrays', () => {
+      const props = {
+        items: [
+          { _i18n: true, en: 'Item 1', pl: 'Pozycja 1' },
+          { _i18n: true, en: 'Item 2', pl: 'Pozycja 2' },
+        ],
+      };
+
+      const resolved = resolveI18nInProps(props, 'pl', testConfig);
+      expect(resolved.items).toEqual(['Pozycja 1', 'Pozycja 2']);
+    });
+
+    test('should recursively resolve nested objects', () => {
+      const props = {
+        header: {
+          title: { _i18n: true, en: 'Welcome', pl: 'Witaj' },
+          subtitle: { _i18n: true, en: 'Hello', pl: 'Cze[' },
+        },
+      };
+
+      const resolved = resolveI18nInProps(props, 'pl', testConfig);
+      expect((resolved.header as any).title).toBe('Witaj');
+      expect((resolved.header as any).subtitle).toBe('Cze[');
+    });
+
+    test('should handle mixed content', () => {
+      const props = {
+        title: { _i18n: true, en: 'Hello', pl: 'Cze[' },
+        count: 5,
+        enabled: true,
+        data: { value: 100 },
+      };
+
+      const resolved = resolveI18nInProps(props, 'en', testConfig);
+      expect(resolved.title).toBe('Hello');
+      expect(resolved.count).toBe(5);
+      expect(resolved.enabled).toBe(true);
+      expect((resolved.data as any).value).toBe(100);
+    });
+  });
+
+  describe('extractLocaleFromPath', () => {
+    test('should extract locale from path with locale prefix', () => {
+      const result = extractLocaleFromPath('/pl/about', testConfig);
+      expect(result.locale).toBe('pl');
+      expect(result.pathWithoutLocale).toBe('/about');
+    });
+
+    test('should handle root path with locale', () => {
+      const result = extractLocaleFromPath('/de', testConfig);
+      expect(result.locale).toBe('de');
+      expect(result.pathWithoutLocale).toBe('/');
+    });
+
+    test('should return null locale for path without prefix', () => {
+      const result = extractLocaleFromPath('/about', testConfig);
+      expect(result.locale).toBeNull();
+      expect(result.pathWithoutLocale).toBe('/about');
+    });
+
+    test('should handle path without leading slash', () => {
+      const result = extractLocaleFromPath('pl/about', testConfig);
+      expect(result.locale).toBe('pl');
+      expect(result.pathWithoutLocale).toBe('/about');
+    });
+
+    test('should not extract invalid locale codes', () => {
+      const result = extractLocaleFromPath('/fr/about', testConfig);
+      expect(result.locale).toBeNull();
+      expect(result.pathWithoutLocale).toBe('/fr/about');
+    });
+  });
+
+  describe('buildLocalizedPath', () => {
+    test('should build localized path', () => {
+      expect(buildLocalizedPath('/about', 'pl')).toBe('/pl/about');
+      expect(buildLocalizedPath('/contact', 'de')).toBe('/de/contact');
+    });
+
+    test('should handle root path', () => {
+      expect(buildLocalizedPath('/', 'pl')).toBe('/pl');
+    });
+
+    test('should handle path without leading slash', () => {
+      expect(buildLocalizedPath('about', 'pl')).toBe('/pl/about');
+    });
+  });
+
+  describe('parseLocaleFromPath', () => {
+    test('should parse locale and return context', () => {
+      const context = parseLocaleFromPath('/pl/about', testConfig);
+      expect(context.locale).toBe('pl');
+      expect(context.pathWithoutLocale).toBe('/about');
+      expect(context.isDefaultLocale).toBe(false);
+    });
+
+    test('should use default locale when no prefix', () => {
+      const context = parseLocaleFromPath('/about', testConfig);
+      expect(context.locale).toBe('en');
+      expect(context.pathWithoutLocale).toBe('/about');
+      expect(context.isDefaultLocale).toBe(true);
+    });
+
+    test('should handle default locale path', () => {
+      const context = parseLocaleFromPath('/en/about', testConfig);
+      expect(context.locale).toBe('en');
+      expect(context.pathWithoutLocale).toBe('/about');
+      expect(context.isDefaultLocale).toBe(true);
+    });
+
+    test('should handle root path', () => {
+      const context = parseLocaleFromPath('/', testConfig);
+      expect(context.locale).toBe('en');
+      expect(context.pathWithoutLocale).toBe('/');
+      expect(context.isDefaultLocale).toBe(true);
+    });
+  });
+});

package/lib/shared/i18n.ts

@@ -0,0 +1,286 @@
+/**
+ * Internationalization (i18n) utilities
+ * Handles inline translation resolution for component props
+ */
+
+import type { I18nValue, I18nConfig, LocaleConfig } from './types/components';
+
+/**
+ * Default i18n configuration
+ */
+export const DEFAULT_I18N_CONFIG: I18nConfig = {
+  defaultLocale: 'en',
+  locales: [
+    { code: 'en', name: 'English', nativeName: 'English', langTag: 'en-US' }
+  ],
+};
+
+// ============================================
+// Locale helper functions
+// ============================================
+
+/**
+ * Get array of locale codes from config
+ */
+export function getLocaleCodes(config: I18nConfig): string[] {
+  return config.locales.map(loc => loc.code);
+}
+
+/**
+ * Find a locale config by its code
+ */
+export function findLocaleByCode(config: I18nConfig, code: string): LocaleConfig | undefined {
+  return config.locales.find(loc => loc.code === code);
+}
+
+/**
+ * Check if a locale code is valid/exists in config
+ */
+export function isValidLocaleCode(config: I18nConfig, code: string): boolean {
+  return config.locales.some(loc => loc.code === code);
+}
+
+// ============================================
+// Config Migration (old string[] -> new LocaleConfig[])
+// ============================================
+
+/**
+ * Convert old locale format (string) to new format (LocaleConfig)
+ */
+function migrateLocaleString(code: string): LocaleConfig {
+  const upperCode = code.toUpperCase();
+  return {
+    code: code.toLowerCase(),
+    name: upperCode,
+    nativeName: upperCode,
+    langTag: `${code.toLowerCase()}-${upperCode}`,
+  };
+}
+
+/**
+ * Check if locales array is in old string format
+ */
+function isOldLocaleFormat(locales: unknown): locales is string[] {
+  return Array.isArray(locales) && locales.length > 0 && typeof locales[0] === 'string';
+}
+
+/**
+ * Migrate i18n config from old format to new format
+ * Old: { defaultLocale: "en", locales: ["en", "pl"] }
+ * New: { defaultLocale: "en", locales: [{ code: "en", name: "EN", ... }] }
+ */
+export function migrateI18nConfig(i18n: unknown): I18nConfig {
+  if (!i18n || typeof i18n !== 'object') {
+    return DEFAULT_I18N_CONFIG;
+  }
+
+  const config = i18n as Record<string, unknown>;
+  const defaultLocale = (config.defaultLocale as string) || 'en';
+  const locales = config.locales;
+
+  if (!locales || !Array.isArray(locales)) {
+    return DEFAULT_I18N_CONFIG;
+  }
+
+  // Migrate old string[] format
+  if (isOldLocaleFormat(locales)) {
+    return {
+      defaultLocale,
+      locales: locales.map(migrateLocaleString),
+    };
+  }
+
+  // Already in new format
+  return {
+    defaultLocale,
+    locales: locales as LocaleConfig[],
+  };
+}
+
+/**
+ * Type guard to check if a value is an I18nValue object
+ */
+export function isI18nValue(value: unknown): value is I18nValue {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    return false;
+  }
+  return '_i18n' in value && (value as Record<string, unknown>)._i18n === true;
+}
+
+/**
+ * Resolve a single translation value for the given locale
+ * Fallback order: exact locale -> default locale -> first available -> empty string
+ */
+export function resolveTranslation(
+  value: I18nValue,
+  locale: string,
+  config: I18nConfig
+): string {
+  // Try exact locale match
+  if (typeof value[locale] === 'string') {
+    return value[locale] as string;
+  }
+
+  // Try default locale
+  if (typeof value[config.defaultLocale] === 'string') {
+    return value[config.defaultLocale] as string;
+  }
+
+  // Get first available translation (skip _i18n marker)
+  for (const key of Object.keys(value)) {
+    if (key !== '_i18n' && typeof value[key] === 'string') {
+      return value[key] as string;
+    }
+  }
+
+  return '';
+}
+
+/**
+ * Resolve a value that might be an I18nValue or a regular value
+ * Returns the original value if not an I18nValue
+ */
+export function resolveI18nValue(
+  value: unknown,
+  locale: string,
+  config: I18nConfig
+): unknown {
+  if (isI18nValue(value)) {
+    return resolveTranslation(value, locale, config);
+  }
+  return value;
+}
+
+/**
+ * Recursively resolve all I18nValue objects in a props object
+ */
+export function resolveI18nInProps(
+  props: Record<string, unknown>,
+  locale: string,
+  config: I18nConfig
+): Record<string, unknown> {
+  const resolved: Record<string, unknown> = {};
+
+  for (const [key, value] of Object.entries(props)) {
+    if (isI18nValue(value)) {
+      resolved[key] = resolveTranslation(value, locale, config);
+    } else if (Array.isArray(value)) {
+      resolved[key] = value.map((item) =>
+        isI18nValue(item) ? resolveTranslation(item, locale, config) : item
+      );
+    } else if (typeof value === 'object' && value !== null) {
+      // Recursively resolve nested objects (but not I18nValue which is already handled)
+      resolved[key] = resolveI18nInProps(
+        value as Record<string, unknown>,
+        locale,
+        config
+      );
+    } else {
+      resolved[key] = value;
+    }
+  }
+
+  return resolved;
+}
+
+/**
+ * Extract locale from URL path prefix
+ * e.g., '/en/about' -> 'en', '/pl/' -> 'pl', '/about' -> null
+ */
+export function extractLocaleFromPath(
+  path: string,
+  config: I18nConfig
+): { locale: string | null; pathWithoutLocale: string } {
+  // Remove leading slash and split
+  const cleanPath = path.startsWith('/') ? path.slice(1) : path;
+  const segments = cleanPath.split('/');
+
+  if (segments.length > 0 && isValidLocaleCode(config, segments[0])) {
+    const locale = segments[0];
+    const pathWithoutLocale = '/' + segments.slice(1).join('/');
+    return { locale, pathWithoutLocale: pathWithoutLocale || '/' };
+  }
+
+  return { locale: null, pathWithoutLocale: path };
+}
+
+/**
+ * Build a localized path
+ * e.g., ('/about', 'pl') -> '/pl/about'
+ */
+export function buildLocalizedPath(path: string, locale: string): string {
+  const cleanPath = path.startsWith('/') ? path : '/' + path;
+  return `/${locale}${cleanPath === '/' ? '' : cleanPath}`;
+}
+
+/**
+ * Locale context containing resolved locale info
+ */
+export interface LocaleContext {
+  /** The effective locale (never null) */
+  locale: string;
+  /** Path with locale prefix removed */
+  pathWithoutLocale: string;
+  /** Whether the current locale is the default */
+  isDefaultLocale: boolean;
+}
+
+/**
+ * Parse locale from path and return full context with effective locale
+ * Combines extractLocaleFromPath + defaultLocale resolution in one call
+ */
+export function parseLocaleFromPath(
+  path: string,
+  config: I18nConfig
+): LocaleContext {
+  const { locale, pathWithoutLocale } = extractLocaleFromPath(path, config);
+  const effectiveLocale = locale || config.defaultLocale;
+
+  return {
+    locale: effectiveLocale,
+    pathWithoutLocale,
+    isDefaultLocale: effectiveLocale === config.defaultLocale
+  };
+}
+
+// ============================================
+// Client-side locale persistence utilities
+// ============================================
+
+const LOCALE_STORAGE_KEY = 'uplo_locale_preference';
+
+/**
+ * Get stored locale preference from localStorage (client-side only)
+ */
+export function getStoredLocale(): string | null {
+  if (typeof window === 'undefined') return null;
+  try {
+    return localStorage.getItem(LOCALE_STORAGE_KEY);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Store locale preference to localStorage (client-side only)
+ */
+export function setStoredLocale(locale: string): void {
+  if (typeof window === 'undefined') return;
+  try {
+    localStorage.setItem(LOCALE_STORAGE_KEY, locale);
+  } catch {
+    // Storage not available
+  }
+}
+
+/**
+ * Clear stored locale preference (client-side only)
+ */
+export function clearStoredLocale(): void {
+  if (typeof window === 'undefined') return;
+  try {
+    localStorage.removeItem(LOCALE_STORAGE_KEY);
+  } catch {
+    // Storage not available
+  }
+}

package/lib/shared/index.ts

@@ -0,0 +1,50 @@
+/**
+ * @meno/core shared exports
+ * Re-exports all types, constants, and utilities from shared modules
+ */
+
+// Types
+export * from './types';
+
+// Constants
+export * from './constants';
+
+// Path utilities
+export * from './pathArrayUtils';
+export * from './treePathUtils';
+export * from './paths';
+
+// Node utilities
+export * from './nodeUtils';
+
+// Style utilities
+export * from './breakpoints';
+export * from './styleUtils';
+export * from './cssProperties';
+export * from './cssGeneration';
+export * from './colorProperties';
+export * from './utilityClassMapper';
+
+// i18n utilities
+export * from './i18n';
+
+// Tree utilities
+export * from './tree/PathBuilder';
+
+// Validation
+export * from './validation';
+
+// Utils
+export * from './utils';
+
+// Registry
+export * from './registry';
+
+// Theme defaults
+export * from './themeDefaults';
+
+// Color variable utilities
+export * from './colorVariableUtils';
+
+// Responsive style utilities
+export * from './responsiveStyleUtils';

package/lib/shared/interfaces/contentProvider.test.ts

@@ -0,0 +1,9 @@
+import { describe, test, expect } from 'bun:test';
+
+describe('contentProvider', () => {
+  test('placeholder test for coverage', () => {
+    // Content provider interface - no logic to test
+    // This placeholder ensures the file appears in coverage reports
+    expect(true).toBe(true);
+  });
+});