@lukso/core 0.1.0-dev.0f1bea5

package/src/services/intl.ts

@@ -0,0 +1,326 @@
+/**
+ * Internationalization Service
+ *
+ * Provides locale-aware formatting for messages, numbers, dates, and times.
+ */
+
+import {
+  createIntl,
+  type FormatNumberOptions,
+  type IntlConfig,
+} from '@formatjs/intl'
+import { signal } from '@preact/signals-core'
+
+/**
+ * Translation messages object type
+ * Maps translation keys to their corresponding string values
+ */
+export type IntlMessages = Record<string, string>
+
+/**
+ * Default format number options
+ * @see https://github.com/formatjs/formatjs/blob/main/packages/ecma402-abstract/types/number.ts
+ */
+const formatNumberDefaultOptions = {
+  maximumFractionDigits: 18,
+}
+
+/**
+ * Intl service interface
+ */
+export interface IntlService {
+  /**
+   * Translate a string based on the key
+   *
+   * @param key - translation key
+   * @param options - optional options for formatMessage (for variable interpolation)
+   * @returns - translated string
+   */
+  formatMessage: (key: string, options?: Record<string, string>) => string
+
+  /**
+   * Number formatting based on the locale
+   *
+   * @param value - number to format
+   * @param options - options for formatNumber
+   * @returns - formatted number
+   */
+  formatNumber: (
+    value: number | string | bigint,
+    options?: FormatNumberOptions
+  ) => string
+
+  /**
+   * Date formatting based on the locale
+   *
+   * @param date - date to format
+   * @returns - formatted date
+   */
+  formatDate: (date?: string | number | Date) => string | undefined
+
+  /**
+   * Time formatting based on the locale
+   *
+   * @param date - date to format
+   * @returns - formatted time
+   */
+  formatTime: (date?: string | number | Date) => string | undefined
+
+  /**
+   * Timestamp formatting based on the locale
+   *
+   * @param timestamp - UNIX timestamp in seconds or milliseconds
+   * @param options - formatting options (predefined format name or custom Intl.DateTimeFormat options)
+   * @returns - formatted date & time string
+   *
+   * @example
+   * ```typescript
+   * const intl = getIntlService();
+   *
+   * // Use predefined shortDateTime format
+   * intl.formatTimestamp(1733251200, 'shortDateTime'); // "Wed, Dec 3, 2025, 16:07"
+   *
+   * // Use custom format options
+   * intl.formatTimestamp(1733251200, { year: '2-digit', month: '2-digit', day: '2-digit' });
+   * // "12/03/25"
+   *
+   * // No options (basic format)
+   * intl.formatTimestamp(1733251200);
+   * ```
+   */
+  formatTimestamp: (
+    timestamp?: number | string,
+    options?: Intl.DateTimeFormatOptions | string
+  ) => string
+
+  /**
+   * Change the locale and optionally update messages
+   *
+   * @param locale - new locale code (e.g., 'en-US', 'de-DE')
+   * @param messages - optional new messages object for the locale
+   */
+  setLocale: (locale: string, messages?: IntlMessages) => void
+
+  /**
+   * Get the current locale
+   *
+   * @returns - current locale code (e.g., 'en-US', 'de-DE')
+   */
+  getLocale: () => string
+
+  /**
+   * Set fallback translations to use when a translation key is missing
+   * Useful when the host app's intl service doesn't have all translations
+   *
+   * @param fallbackMessages - translations to use as fallback
+   *
+   * @example
+   * ```typescript
+   * // After intl service is initialized by host app
+   * intl.setFallbackTranslations(defaultMessages);
+   * ```
+   */
+  setFallbackTranslations: (fallbackMessages: IntlMessages) => void
+
+  /**
+   * Signal that tracks locale changes
+   * Use this signal to reactively update UI when locale changes
+   */
+  localeChanged: { value: number }
+}
+
+/**
+ * Default configuration for intl
+ */
+export const defaultConfig: IntlConfig = {
+  locale: 'en-US',
+  messages: {},
+  formats: {},
+}
+
+/**
+ * Global intl service instance
+ */
+let intlService: IntlService | null = null
+
+/**
+ * Create a new intl service instance
+ *
+ * @param config - intl configuration with locale and messages
+ * @returns IntlService instance with formatting methods
+ *
+ * @example
+ * ```typescript
+ * import { createIntlService } from '@lukso/core/services/intl';
+ *
+ * const intl = createIntlService({
+ *   locale: 'en-US',
+ *   messages: customMessages,
+ * });
+ *
+ * const translated = intl.formatMessage('app.title');
+ * const formatted = intl.formatNumber(1234.56);
+ * const currentLocale = intl.getLocale(); // 'en-US'
+ *
+ * // Change locale
+ * intl.setLocale('de-DE', germanMessages);
+ * console.log(intl.getLocale()); // 'de-DE'
+ * ```
+ */
+export function createIntlService(
+  config: IntlConfig = defaultConfig
+): IntlService {
+  let currentConfig = { ...defaultConfig, ...config }
+  let intl = createIntl({ ...currentConfig, defaultLocale: 'en-US' })
+  const localeChanged = signal(0)
+  let fallbackMessages: IntlMessages = {}
+
+  return {
+    formatMessage: (key: string, options?: Record<string, string>): string => {
+      try {
+        const result = intl.formatMessage({ id: key }, options)
+
+        if (result && result !== key) {
+          return result
+        }
+
+        // If no translation found, check fallback
+        if (fallbackMessages[key]) {
+          return fallbackMessages[key]
+        }
+
+        return key
+      } catch {
+        // On error, try fallback
+        return fallbackMessages[key] || key
+      }
+    },
+
+    formatNumber: (
+      value: number | string | bigint,
+      options: FormatNumberOptions = {}
+    ): string => {
+      if (value === null || value === undefined) {
+        return '0'
+      }
+
+      const _value =
+        typeof value === 'string' ? Number.parseFloat(value) : value
+
+      const mergedOptions = {
+        ...formatNumberDefaultOptions,
+        ...options,
+      }
+
+      return intl.formatNumber(_value as number, mergedOptions) || ''
+    },
+
+    formatDate: (date?: string | number | Date): string => {
+      return intl.formatDate(date)
+    },
+
+    formatTime: (date?: string | number | Date): string => {
+      return intl.formatTime(date)
+    },
+
+    formatTimestamp: (
+      timestamp?: number | string,
+      options?: Intl.DateTimeFormatOptions | string
+    ): string => {
+      if (!timestamp) return ''
+
+      const time = typeof timestamp === 'string' ? Number(timestamp) : timestamp
+      const date =
+        time < 10_000_000_000
+          ? new Date(time * 1000) // seconds
+          : new Date(time) // milliseconds
+
+      // Handle predefined format
+      if (typeof options === 'string') {
+        const dateTimeOptions = currentConfig.formats?.date?.[
+          options
+        ] as Intl.DateTimeFormatOptions
+
+        if (dateTimeOptions) {
+          return new Intl.DateTimeFormat(
+            currentConfig.locale,
+            dateTimeOptions
+          ).format(date)
+        }
+
+        // Fallback to default format if predefined format not found
+        return intl.formatDate(date) || ''
+      }
+
+      // For normal @formatjs/intl options
+      return intl.formatDate(date, options) || ''
+    },
+
+    setLocale: (locale: string, messages?: IntlMessages): void => {
+      currentConfig = {
+        ...currentConfig,
+        locale,
+        messages: messages || currentConfig.messages,
+      }
+      intl = createIntl({
+        ...currentConfig,
+        defaultLocale: 'en-US',
+      })
+      localeChanged.value += 1
+    },
+
+    getLocale: (): string => {
+      return currentConfig.locale
+    },
+
+    setFallbackTranslations: (fallbackMessagesInput: IntlMessages): void => {
+      fallbackMessages = fallbackMessagesInput
+    },
+
+    localeChanged,
+  }
+}
+
+/**
+ * Set the global intl service
+ * Call this once from your app initialization
+ *
+ * @param service - IntlService instance
+ *
+ * @example
+ * ```typescript
+ * import { setIntlService, createIntlService } from '@lukso/core/services/intl';
+ *
+ * const intl = createIntlService(config);
+ * setIntlService(intl);
+ * ```
+ */
+export function setIntlService(service: IntlService): void {
+  intlService = service
+}
+
+/**
+ * Get the current global intl service
+ * Returns null if no service has been set
+ *
+ * @example
+ * ```typescript
+ * import { getIntlService } from '@lukso/core/services/intl';
+ *
+ * const intl = getIntlService();
+ * if (intl) {
+ *   console.log(intl.getLocale());
+ * }
+ * ```
+ */
+export function getIntlService(): IntlService | null {
+  return intlService
+}
+
+/**
+ * Clear the global intl service
+ * Useful for testing or cleanup
+ */
+export function clearIntlService(): void {
+  intlService = null
+}

package/src/utils/__tests__/browserInfo.spec.ts

@@ -0,0 +1,310 @@
+import { describe, expect, it } from 'vitest'
+import type { BrowserInfo, BrowserName } from '../browserInfo'
+import { browserInfo, EXTENSION_STORE_LINKS } from '../browserInfo'
+
+describe('browserInfo', () => {
+  describe('browserInfo function', () => {
+    it('should return a BrowserInfo object', () => {
+      const mockDeviceService = {
+        isChrome: true,
+        isBrave: false,
+        isFirefox: false,
+        isSafari: false,
+        isEdge: false,
+        isOpera: false,
+      }
+
+      const info = browserInfo(mockDeviceService as any)
+
+      expect(info).toBeDefined()
+      expect(typeof info).toBe('object')
+      expect(info).toHaveProperty('id')
+      expect(info).toHaveProperty('name')
+      expect(info).toHaveProperty('icon')
+      expect(info).toHaveProperty('storeLink')
+    })
+
+    it('should detect Chrome browser', () => {
+      const mockDeviceService = {
+        isChrome: true,
+        isBrave: false,
+        isFirefox: false,
+        isSafari: false,
+        isEdge: false,
+        isOpera: false,
+      }
+
+      const info = browserInfo(mockDeviceService as any)
+
+      expect(info.id).toBe('chrome')
+      expect(info.name).toBe('Chrome')
+      expect(info.icon).toBe('logo-chrome')
+      expect(info.storeLink).toBe(EXTENSION_STORE_LINKS.chrome)
+    })
+
+    it('should detect Brave browser', () => {
+      const mockDeviceService = {
+        isChrome: false,
+        isBrave: true,
+        isFirefox: false,
+        isSafari: false,
+        isEdge: false,
+        isOpera: false,
+      }
+
+      const info = browserInfo(mockDeviceService as any)
+
+      expect(info.id).toBe('brave')
+      expect(info.name).toBe('Brave')
+      expect(info.icon).toBe('logo-brave')
+      expect(info.storeLink).toBe(EXTENSION_STORE_LINKS.brave)
+    })
+
+    it('should detect Edge browser', () => {
+      const mockDeviceService = {
+        isChrome: false,
+        isBrave: false,
+        isFirefox: false,
+        isSafari: false,
+        isEdge: true,
+        isOpera: false,
+      }
+
+      const info = browserInfo(mockDeviceService as any)
+
+      expect(info.id).toBe('edge')
+      expect(info.name).toBe('Edge')
+      expect(info.icon).toBe('logo-edge')
+      expect(info.storeLink).toBe(EXTENSION_STORE_LINKS.edge)
+    })
+
+    it('should detect Opera browser', () => {
+      const mockDeviceService = {
+        isChrome: false,
+        isBrave: false,
+        isFirefox: false,
+        isSafari: false,
+        isEdge: false,
+        isOpera: true,
+      }
+
+      const info = browserInfo(mockDeviceService as any)
+
+      expect(info.id).toBe('opera')
+      expect(info.name).toBe('Opera')
+      expect(info.icon).toBe('logo-opera')
+      expect(info.storeLink).toBe(EXTENSION_STORE_LINKS.opera)
+    })
+
+    it('should detect Firefox browser', () => {
+      const mockDeviceService = {
+        isChrome: false,
+        isBrave: false,
+        isFirefox: true,
+        isSafari: false,
+        isEdge: false,
+        isOpera: false,
+      }
+
+      const info = browserInfo(mockDeviceService as any)
+
+      expect(info.id).toBe('firefox')
+      expect(info.name).toBe('Firefox')
+      expect(info.icon).toBe('logo-firefox')
+      expect(info.storeLink).toBe(EXTENSION_STORE_LINKS.firefox)
+    })
+
+    it('should detect Safari browser', () => {
+      const mockDeviceService = {
+        isChrome: false,
+        isBrave: false,
+        isFirefox: false,
+        isSafari: true,
+        isEdge: false,
+        isOpera: false,
+      }
+
+      const info = browserInfo(mockDeviceService as any)
+
+      expect(info.id).toBe('safari')
+      expect(info.name).toBe('Safari')
+      expect(info.icon).toBe('logo-safari')
+      expect(info.storeLink).toBe(EXTENSION_STORE_LINKS.safari)
+    })
+
+    it('should prioritize Brave over Chrome', () => {
+      const mockDeviceService = {
+        isChrome: true,
+        isBrave: true,
+        isFirefox: false,
+        isSafari: false,
+        isEdge: false,
+        isOpera: false,
+      }
+
+      const info = browserInfo(mockDeviceService as any)
+
+      expect(info.id).toBe('brave')
+      expect(info.name).toBe('Brave')
+    })
+
+    it('should prioritize Edge over Chrome', () => {
+      const mockDeviceService = {
+        isChrome: true,
+        isBrave: false,
+        isFirefox: false,
+        isSafari: false,
+        isEdge: true,
+        isOpera: false,
+      }
+
+      const info = browserInfo(mockDeviceService as any)
+
+      expect(info.id).toBe('edge')
+      expect(info.name).toBe('Edge')
+    })
+
+    it('should prioritize Opera over Chrome', () => {
+      const mockDeviceService = {
+        isChrome: true,
+        isBrave: false,
+        isFirefox: false,
+        isSafari: false,
+        isEdge: false,
+        isOpera: true,
+      }
+
+      const info = browserInfo(mockDeviceService as any)
+
+      expect(info.id).toBe('opera')
+      expect(info.name).toBe('Opera')
+    })
+
+    it('should return default browser when none detected', () => {
+      const mockDeviceService = {
+        isChrome: false,
+        isBrave: false,
+        isFirefox: false,
+        isSafari: false,
+        isEdge: false,
+        isOpera: false,
+      }
+
+      const info = browserInfo(mockDeviceService as any)
+
+      expect(info.id).toBe('chrome')
+      expect(info.name).toBe('')
+      expect(info.icon).toBe('')
+    })
+
+    it('should return correct BrowserName type', () => {
+      const mockDeviceService = {
+        isChrome: true,
+        isBrave: false,
+        isFirefox: false,
+        isSafari: false,
+        isEdge: false,
+        isOpera: false,
+      }
+
+      const info: BrowserInfo = browserInfo(mockDeviceService as any)
+      const validBrowserNames: BrowserName[] = [
+        'chrome',
+        'safari',
+        'firefox',
+        'edge',
+        'opera',
+        'brave',
+      ]
+
+      expect(validBrowserNames).toContain(info.id)
+    })
+
+    it('should merge defaults with detected browser info', () => {
+      const mockDeviceService = {
+        isChrome: false,
+        isBrave: true,
+        isFirefox: false,
+        isSafari: false,
+        isEdge: false,
+        isOpera: false,
+      }
+
+      const info = browserInfo(mockDeviceService as any)
+
+      // Should have all properties from defaults and detected browser
+      expect(info).toEqual({
+        id: 'brave',
+        name: 'Brave',
+        icon: 'logo-brave',
+        storeLink: EXTENSION_STORE_LINKS.brave,
+      })
+    })
+
+    it('should handle multiple calls consistently', () => {
+      const mockDeviceService = {
+        isChrome: true,
+        isBrave: false,
+        isFirefox: false,
+        isSafari: false,
+        isEdge: false,
+        isOpera: false,
+      }
+
+      const info1 = browserInfo(mockDeviceService as any)
+      const info2 = browserInfo(mockDeviceService as any)
+
+      expect(info1).toEqual(info2)
+    })
+
+    it('should have all required properties for BrowserInfo type', () => {
+      const mockDeviceService = {
+        isChrome: true,
+        isBrave: false,
+        isFirefox: false,
+        isSafari: false,
+        isEdge: false,
+        isOpera: false,
+      }
+
+      const info = browserInfo(mockDeviceService as any)
+
+      // Verify TypeScript would accept this as BrowserInfo
+      const expectedKeys: (keyof BrowserInfo)[] = [
+        'id',
+        'name',
+        'icon',
+        'storeLink',
+      ]
+      expectedKeys.forEach((key) => {
+        expect(info).toHaveProperty(key)
+      })
+    })
+
+    it('should detect all browser types independently', () => {
+      const browsers = [
+        { isChrome: true, expected: 'chrome' },
+        { isBrave: true, expected: 'brave' },
+        { isEdge: true, expected: 'edge' },
+        { isOpera: true, expected: 'opera' },
+        { isFirefox: true, expected: 'firefox' },
+        { isSafari: true, expected: 'safari' },
+      ]
+
+      browsers.forEach(({ expected, ...detection }) => {
+        const mockDeviceService = {
+          isChrome: false,
+          isBrave: false,
+          isFirefox: false,
+          isSafari: false,
+          isEdge: false,
+          isOpera: false,
+          ...detection,
+        }
+
+        const info = browserInfo(mockDeviceService as any)
+        expect(info.id).toBe(expected)
+      })
+    })
+  })
+})

package/src/utils/__tests__/slug.spec.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest'
+
+import { slug } from '../slug'
+
+describe('slug', () => {
+  it('returns an empty string for undefined or empty input', () => {
+    expect(slug()).toBe('')
+    // @ts-expect-error
+    expect(slug(null)).toBe('')
+    expect(slug('')).toBe('')
+  })
+
+  it('converts all characters to lowercase', () => {
+    expect(slug('TEST')).toBe('test')
+  })
+
+  it('converts spaces to hyphens', () => {
+    expect(slug('some attribute')).toBe('some-attribute')
+  })
+
+  it('keeps same output as input', () => {
+    expect(slug('test@slug')).toBe('test@slug')
+    expect(slug('-test-slug-')).toBe('-test-slug-')
+    expect(slug('test---slug')).toBe('test---slug')
+  })
+})