@refraction-ui/astro 0.16.1 → 0.17.1

package/dist/emoji-picker/emoji-picker.styles.ts

@@ -1,7 +1,7 @@
 import { cva } from '../shared/index.ts'
 
 export const emojiPickerContainerStyles =
-  'w-80 rounded-lg border bg-popover text-popover-foreground shadow-md'
+  'w-80 rounded-lg border bg-popover text-popover-foreground shadow-md motion-safe:animate-fade-in-scale origin-top'
 
 export const emojiPickerSearchStyles =
   'w-full border-b px-3 py-2 text-sm bg-transparent outline-none placeholder:text-muted-foreground'
@@ -10,7 +10,7 @@ export const emojiPickerCategoryBarStyles =
   'flex border-b px-1'
 
 export const emojiPickerCategoryTabVariants = cva({
-  base: 'flex-1 py-1.5 text-center text-lg cursor-pointer hover:bg-accent rounded-md transition-colors',
+  base: 'flex-1 py-1.5 text-center text-lg cursor-pointer hover:bg-accent rounded-md transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
   variants: {
     state: {
       active: 'bg-accent',
@@ -26,7 +26,15 @@ export const emojiPickerGridStyles =
   'grid grid-cols-8 gap-0.5 p-2 max-h-64 overflow-y-auto'
 
 export const emojiPickerEmojiButtonStyles =
-  'flex items-center justify-center h-8 w-8 rounded cursor-pointer text-lg hover:bg-accent transition-colors'
+  'flex items-center justify-center h-8 w-8 rounded cursor-pointer text-lg transition-transform duration-100 ease-out hover:bg-accent hover:scale-125 active:scale-95 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring motion-reduce:transition-none motion-reduce:hover:scale-100'
 
 export const emojiPickerSectionLabelStyles =
   'px-2 py-1 text-xs font-medium text-muted-foreground'
+
+/** The swappable category/search/sticker panel; fades on category switch. */
+export const emojiPickerPanelStyles =
+  'motion-safe:animate-fade-in origin-top'
+
+/** A single sticker cell in the sticker tab. */
+export const emojiPickerStickerButtonStyles =
+  'flex items-center justify-center rounded-lg p-1.5 aspect-square cursor-pointer transition-transform duration-100 ease-out hover:bg-accent hover:scale-110 active:scale-95 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring motion-reduce:transition-none motion-reduce:hover:scale-100'

package/dist/emoji-picker/index.ts

@@ -9,11 +9,29 @@ export {
   EMOJI_DATA,
   EMOJI_CATEGORIES,
   CATEGORY_LABELS,
+  EMOJI_COUNT_TOTAL,
+  SHORTCODE_ALIASES,
   getAllEmojis,
+  resolveShortcode,
+  buildShortcodeMap,
+  searchEmojis,
   type EmojiCategory,
   type EmojiEntry,
 } from './emoji-data.js'
 
+export {
+  twemojiFilename,
+  twemojiAssetUrl,
+  DEFAULT_TWEMOJI_BASE_URL,
+} from './twemoji.js'
+
+export {
+  STARTER_STICKER_SET,
+  type StickerItem,
+  type StickerSet,
+  type StickerKind,
+} from './stickers.js'
+
 export {
   emojiPickerContainerStyles,
   emojiPickerSearchStyles,
@@ -22,4 +40,6 @@ export {
   emojiPickerGridStyles,
   emojiPickerEmojiButtonStyles,
   emojiPickerSectionLabelStyles,
+  emojiPickerPanelStyles,
+  emojiPickerStickerButtonStyles,
 } from './emoji-picker.styles.js'

package/dist/emoji-picker/stickers.ts

@@ -0,0 +1,146 @@
+/**
+ * Sticker seam — types + a small bundled starter pack.
+ *
+ * Stickers are host-extensible: a consumer (or a future bundled pack) supplies
+ * `StickerSet`s and the picker renders them in a dedicated tab. Three render
+ * paths are supported so the API is ready for animated content without any
+ * heavy dependency in the core:
+ *   - `kind: 'svg'`   — inline SVG markup (can self-animate via SMIL, no JS).
+ *   - `kind: 'image'` — a URL to a static or animated (WebP/GIF/APNG) asset.
+ *   - `kind: 'lottie'`— a URL/JSON handed to a host-provided Lottie player.
+ *
+ * The starter pack below ships a handful of simple, consistent flat stickers
+ * (128×128, one visual language) so the tab is not empty out of the box, and
+ * proves the animated render path with a self-animating SMIL heart — no Lottie
+ * runtime required.
+ */
+
+export type StickerKind = 'svg' | 'image' | 'lottie'
+
+export interface StickerItem {
+  /** Stable id (unique within its set). */
+  id: string
+  /** Accessible label / alt text. */
+  label: string
+  kind: StickerKind
+  /**
+   * The sticker payload: inline SVG markup (`svg`), an asset URL (`image`), or
+   * a Lottie JSON URL or serialized object (`lottie`).
+   */
+  source: string
+  /** Search keywords. */
+  keywords?: string[]
+  /** True when the sticker animates (drives reduced-motion handling). */
+  animated?: boolean
+}
+
+export interface StickerSet {
+  /** Stable id (unique across sets). */
+  id: string
+  /** Human-readable set name (tab tooltip). */
+  label: string
+  /** A representative emoji/char for the set's tab icon. */
+  icon?: string
+  stickers: StickerItem[]
+}
+
+const svg = (inner: string): string =>
+  `<svg viewBox="0 0 128 128" xmlns="http://www.w3.org/2000/svg" width="100%" height="100%">${inner}</svg>`
+
+/**
+ * Refraction starter sticker pack — a tasteful, consistent flat set. The
+ * `pulse-heart` sticker self-animates via SMIL to demonstrate the animated
+ * render path; the rest are static.
+ */
+export const STARTER_STICKER_SET: StickerSet = {
+  id: 'refraction-starter',
+  label: 'Refraction',
+  icon: '⭐',
+  stickers: [
+    {
+      id: 'pulse-heart',
+      label: 'Pulsing heart',
+      kind: 'svg',
+      animated: true,
+      keywords: ['heart', 'love', 'like'],
+      source: svg(
+        `<g fill="#ff5a7a"><path d="M64 112C34 90 16 72 16 50a26 26 0 0 1 48-14 26 26 0 0 1 48 14c0 22-18 40-48 62Z">` +
+          `<animateTransform attributeName="transform" type="scale" additive="sum" values="1;1.08;1" dur="1s" repeatCount="indefinite" calcMode="spline" keySplines="0.4 0 0.2 1;0.4 0 0.2 1" keyTimes="0;0.5;1"/>` +
+          `</path></g>`,
+      ),
+    },
+    {
+      id: 'star',
+      label: 'Gold star',
+      kind: 'svg',
+      keywords: ['star', 'favorite', 'award'],
+      source: svg(
+        `<path fill="#ffc93c" d="M64 14l14 30 33 4-24 23 6 33-29-16-29 16 6-33-24-23 33-4z"/>`,
+      ),
+    },
+    {
+      id: 'thumbs-up',
+      label: 'Thumbs up',
+      kind: 'svg',
+      keywords: ['thumbsup', 'like', 'yes', 'approve'],
+      source: svg(
+        `<g fill="#4c9aff"><rect x="20" y="56" width="20" height="50" rx="5"/>` +
+          `<path d="M48 56l16-34c9 0 14 7 12 18l-3 14h26c8 0 13 8 10 16l-9 26c-2 6-8 10-14 10H48Z"/></g>`,
+      ),
+    },
+    {
+      id: 'party',
+      label: 'Party popper',
+      kind: 'svg',
+      keywords: ['party', 'celebrate', 'tada', 'confetti'],
+      source: svg(
+        `<path fill="#ff8a3d" d="M18 110L52 44l32 32z"/>` +
+          `<circle cx="92" cy="30" r="6" fill="#ff5a7a"/><circle cx="110" cy="52" r="5" fill="#ffc93c"/>` +
+          `<circle cx="70" cy="20" r="5" fill="#4c9aff"/><circle cx="104" cy="82" r="6" fill="#5ad19a"/>`,
+      ),
+    },
+    {
+      id: 'smiley',
+      label: 'Smiley blob',
+      kind: 'svg',
+      keywords: ['happy', 'smile', 'face'],
+      source: svg(
+        `<circle cx="64" cy="64" r="46" fill="#ffd23f"/>` +
+          `<circle cx="48" cy="56" r="6" fill="#3a2d00"/><circle cx="80" cy="56" r="6" fill="#3a2d00"/>` +
+          `<path d="M44 78a24 24 0 0 0 40 0" stroke="#3a2d00" stroke-width="6" fill="none" stroke-linecap="round"/>`,
+      ),
+    },
+    {
+      id: 'fire',
+      label: 'Fire',
+      kind: 'svg',
+      keywords: ['fire', 'hot', 'lit'],
+      source: svg(
+        `<path fill="#ff6b35" d="M64 12c8 22-14 26-14 46a14 14 0 0 0 28 0c0-6-2-10-2-14 10 6 16 18 16 30a28 28 0 0 1-56 0c0-30 20-40 28-62Z"/>` +
+          `<path fill="#ffd23f" d="M64 62c4 8-6 10-6 20a10 10 0 0 0 20 0c0-8-8-12-14-20Z"/>`,
+      ),
+    },
+    {
+      id: 'check',
+      label: 'Check',
+      kind: 'svg',
+      keywords: ['check', 'done', 'ok', 'yes'],
+      source: svg(
+        `<circle cx="64" cy="64" r="46" fill="#5ad19a"/>` +
+          `<path d="M42 66l14 14 30-32" stroke="#fff" stroke-width="8" fill="none" stroke-linecap="round" stroke-linejoin="round"/>`,
+      ),
+    },
+    {
+      id: 'heart-eyes',
+      label: 'Love it',
+      kind: 'svg',
+      keywords: ['love', 'heart', 'adore'],
+      source: svg(
+        `<circle cx="64" cy="64" r="46" fill="#ffd23f"/>` +
+          `<path fill="#ff5a7a" d="M40 50c5-6 13-2 13 4 0 5-6 9-13 14-7-5-13-9-13-14 0-6 8-10 13-4Z"/>` +
+          `<path fill="#ff5a7a" d="M88 50c5-6 13-2 13 4 0 5-6 9-13 14-7-5-13-9-13-14 0-6 8-10 13-4Z"/>` +
+          `<path d="M44 84a24 24 0 0 0 40 0" stroke="#3a2d00" stroke-width="6" fill="none" stroke-linecap="round"/>`,
+      ),
+    },
+  ],
+}

package/dist/emoji-picker/twemoji.ts

@@ -0,0 +1,60 @@
+/**
+ * Twemoji asset resolution — maps a native emoji glyph to its Twemoji SVG
+ * filename/URL. This is the data half of the `emojiRenderer` seam: it lets the
+ * React/Astro adapters render a UNIFORM emoji set (one look on every OS) instead
+ * of per-platform native glyphs, WhatsApp-style, by lazily loading one small SVG
+ * per glyph from a CDN (or a self-hosted mirror) — nothing is bundled eagerly.
+ *
+ * Twemoji graphics are © Twitter / the Twemoji contributors, licensed CC-BY 4.0.
+ * Consumers rendering with Twemoji must preserve that attribution (see the
+ * package README / NOTICE).
+ *
+ * The filename algorithm mirrors upstream `twemoji.toCodePoint`: surrogate
+ * pairs are combined to codepoints, and the U+FE0F variation selector is
+ * stripped from non-ZWJ sequences (Twemoji names files without it).
+ */
+
+/** Default CDN base for Twemoji SVG assets (jsDelivr, pinned). */
+export const DEFAULT_TWEMOJI_BASE_URL =
+  'https://cdn.jsdelivr.net/gh/jdecked/twemoji@15.1.0/assets/svg/'
+
+const ZWJ = '‍'
+const VARIATION_SELECTOR_16 = /️/g
+
+/** Combine surrogate pairs into dash-joined lowercase hex codepoints. */
+function toCodePoint(input: string): string {
+  const parts: string[] = []
+  let pending = 0
+  let i = 0
+  while (i < input.length) {
+    const c = input.charCodeAt(i++)
+    if (pending) {
+      parts.push((0x10000 + ((pending - 0xd800) << 10) + (c - 0xdc00)).toString(16))
+      pending = 0
+    } else if (c >= 0xd800 && c <= 0xdbff) {
+      pending = c
+    } else {
+      parts.push(c.toString(16))
+    }
+  }
+  return parts.join('-')
+}
+
+/**
+ * Twemoji asset filename (without extension) for a glyph, e.g. `1f600`,
+ * `1f1fa-1f1f8`, `2764` (heart, FE0F stripped).
+ */
+export function twemojiFilename(emoji: string): string {
+  // Keep FE0F only for ZWJ sequences, matching upstream Twemoji naming.
+  const normalized = emoji.indexOf(ZWJ) < 0 ? emoji.replace(VARIATION_SELECTOR_16, '') : emoji
+  return toCodePoint(normalized)
+}
+
+/** Full Twemoji SVG URL for a glyph. */
+export function twemojiAssetUrl(
+  emoji: string,
+  baseUrl: string = DEFAULT_TWEMOJI_BASE_URL,
+): string {
+  const base = baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`
+  return `${base}${twemojiFilename(emoji)}.svg`
+}

package/dist/i18n/countries.ts

@@ -0,0 +1,122 @@
+/**
+ * Country type and registry for i18n support.
+ */
+
+export interface Country {
+  code: string
+  name: string
+  flag: string
+  defaultLanguages: string[]
+  timezone?: string
+}
+
+export const COUNTRIES: Record<string, Country> = {
+  // North America
+  'US': { code: 'US', name: 'United States',  flag: '🇺🇸', defaultLanguages: ['en'], timezone: 'America/New_York' },
+  'CA': { code: 'CA', name: 'Canada',         flag: '🇨🇦', defaultLanguages: ['en', 'fr'], timezone: 'America/Toronto' },
+  'MX': { code: 'MX', name: 'Mexico',         flag: '🇲🇽', defaultLanguages: ['es'], timezone: 'America/Mexico_City' },
+
+  // UK & Ireland
+  'GB': { code: 'GB', name: 'United Kingdom',  flag: '🇬🇧', defaultLanguages: ['en'], timezone: 'Europe/London' },
+  'IE': { code: 'IE', name: 'Ireland',         flag: '🇮🇪', defaultLanguages: ['en'], timezone: 'Europe/Dublin' },
+
+  // Oceania
+  'AU': { code: 'AU', name: 'Australia',       flag: '🇦🇺', defaultLanguages: ['en'], timezone: 'Australia/Sydney' },
+  'NZ': { code: 'NZ', name: 'New Zealand',     flag: '🇳🇿', defaultLanguages: ['en'], timezone: 'Pacific/Auckland' },
+
+  // South Asia
+  'IN': { code: 'IN', name: 'India',           flag: '🇮🇳', defaultLanguages: ['hi', 'en'], timezone: 'Asia/Kolkata' },
+  'PK': { code: 'PK', name: 'Pakistan',        flag: '🇵🇰', defaultLanguages: ['ur', 'en'], timezone: 'Asia/Karachi' },
+  'BD': { code: 'BD', name: 'Bangladesh',      flag: '🇧🇩', defaultLanguages: ['bn'], timezone: 'Asia/Dhaka' },
+  'LK': { code: 'LK', name: 'Sri Lanka',       flag: '🇱🇰', defaultLanguages: ['ta', 'en'], timezone: 'Asia/Colombo' },
+  'NP': { code: 'NP', name: 'Nepal',           flag: '🇳🇵', defaultLanguages: ['hi', 'en'], timezone: 'Asia/Kathmandu' },
+
+  // Western Europe
+  'FR': { code: 'FR', name: 'France',          flag: '🇫🇷', defaultLanguages: ['fr'], timezone: 'Europe/Paris' },
+  'DE': { code: 'DE', name: 'Germany',         flag: '🇩🇪', defaultLanguages: ['de'], timezone: 'Europe/Berlin' },
+  'ES': { code: 'ES', name: 'Spain',           flag: '🇪🇸', defaultLanguages: ['es'], timezone: 'Europe/Madrid' },
+  'IT': { code: 'IT', name: 'Italy',           flag: '🇮🇹', defaultLanguages: ['it'], timezone: 'Europe/Rome' },
+  'PT': { code: 'PT', name: 'Portugal',        flag: '🇵🇹', defaultLanguages: ['pt'], timezone: 'Europe/Lisbon' },
+  'NL': { code: 'NL', name: 'Netherlands',     flag: '🇳🇱', defaultLanguages: ['nl'], timezone: 'Europe/Amsterdam' },
+  'BE': { code: 'BE', name: 'Belgium',         flag: '🇧🇪', defaultLanguages: ['nl', 'fr', 'de'], timezone: 'Europe/Brussels' },
+  'CH': { code: 'CH', name: 'Switzerland',     flag: '🇨🇭', defaultLanguages: ['de', 'fr', 'it'], timezone: 'Europe/Zurich' },
+  'AT': { code: 'AT', name: 'Austria',         flag: '🇦🇹', defaultLanguages: ['de'], timezone: 'Europe/Vienna' },
+
+  // Nordic
+  'SE': { code: 'SE', name: 'Sweden',          flag: '🇸🇪', defaultLanguages: ['sv'], timezone: 'Europe/Stockholm' },
+  'NO': { code: 'NO', name: 'Norway',          flag: '🇳🇴', defaultLanguages: ['no'], timezone: 'Europe/Oslo' },
+  'DK': { code: 'DK', name: 'Denmark',         flag: '🇩🇰', defaultLanguages: ['da'], timezone: 'Europe/Copenhagen' },
+  'FI': { code: 'FI', name: 'Finland',         flag: '🇫🇮', defaultLanguages: ['fi'], timezone: 'Europe/Helsinki' },
+
+  // Eastern Europe
+  'PL': { code: 'PL', name: 'Poland',          flag: '🇵🇱', defaultLanguages: ['pl'], timezone: 'Europe/Warsaw' },
+  'CZ': { code: 'CZ', name: 'Czech Republic',  flag: '🇨🇿', defaultLanguages: ['cs'], timezone: 'Europe/Prague' },
+  'RO': { code: 'RO', name: 'Romania',         flag: '🇷🇴', defaultLanguages: ['ro'], timezone: 'Europe/Bucharest' },
+  'HU': { code: 'HU', name: 'Hungary',         flag: '🇭🇺', defaultLanguages: ['hu'], timezone: 'Europe/Budapest' },
+  'BG': { code: 'BG', name: 'Bulgaria',        flag: '🇧🇬', defaultLanguages: ['bg'], timezone: 'Europe/Sofia' },
+  'HR': { code: 'HR', name: 'Croatia',         flag: '🇭🇷', defaultLanguages: ['hr'], timezone: 'Europe/Zagreb' },
+  'SK': { code: 'SK', name: 'Slovakia',        flag: '🇸🇰', defaultLanguages: ['sk'], timezone: 'Europe/Bratislava' },
+  'SI': { code: 'SI', name: 'Slovenia',        flag: '🇸🇮', defaultLanguages: ['sl'], timezone: 'Europe/Ljubljana' },
+  'RS': { code: 'RS', name: 'Serbia',          flag: '🇷🇸', defaultLanguages: ['sr'], timezone: 'Europe/Belgrade' },
+  'UA': { code: 'UA', name: 'Ukraine',         flag: '🇺🇦', defaultLanguages: ['uk'], timezone: 'Europe/Kyiv' },
+  'RU': { code: 'RU', name: 'Russia',          flag: '🇷🇺', defaultLanguages: ['ru'], timezone: 'Europe/Moscow' },
+  'TR': { code: 'TR', name: 'Turkey',          flag: '🇹🇷', defaultLanguages: ['tr'], timezone: 'Europe/Istanbul' },
+  'GR': { code: 'GR', name: 'Greece',          flag: '🇬🇷', defaultLanguages: ['el'], timezone: 'Europe/Athens' },
+
+  // East Asia
+  'JP': { code: 'JP', name: 'Japan',           flag: '🇯🇵', defaultLanguages: ['ja'], timezone: 'Asia/Tokyo' },
+  'KR': { code: 'KR', name: 'South Korea',     flag: '🇰🇷', defaultLanguages: ['ko'], timezone: 'Asia/Seoul' },
+  'CN': { code: 'CN', name: 'China',           flag: '🇨🇳', defaultLanguages: ['zh'], timezone: 'Asia/Shanghai' },
+  'TW': { code: 'TW', name: 'Taiwan',          flag: '🇹🇼', defaultLanguages: ['zh'], timezone: 'Asia/Taipei' },
+
+  // Southeast Asia
+  'TH': { code: 'TH', name: 'Thailand',        flag: '🇹🇭', defaultLanguages: ['th'], timezone: 'Asia/Bangkok' },
+  'VN': { code: 'VN', name: 'Vietnam',         flag: '🇻🇳', defaultLanguages: ['vi'], timezone: 'Asia/Ho_Chi_Minh' },
+  'ID': { code: 'ID', name: 'Indonesia',       flag: '🇮🇩', defaultLanguages: ['id'], timezone: 'Asia/Jakarta' },
+  'MY': { code: 'MY', name: 'Malaysia',        flag: '🇲🇾', defaultLanguages: ['ms', 'en'], timezone: 'Asia/Kuala_Lumpur' },
+  'PH': { code: 'PH', name: 'Philippines',     flag: '🇵🇭', defaultLanguages: ['en'], timezone: 'Asia/Manila' },
+  'SG': { code: 'SG', name: 'Singapore',       flag: '🇸🇬', defaultLanguages: ['en', 'ms', 'zh'], timezone: 'Asia/Singapore' },
+
+  // South America
+  'BR': { code: 'BR', name: 'Brazil',          flag: '🇧🇷', defaultLanguages: ['pt'], timezone: 'America/Sao_Paulo' },
+  'AR': { code: 'AR', name: 'Argentina',       flag: '🇦🇷', defaultLanguages: ['es'], timezone: 'America/Argentina/Buenos_Aires' },
+  'CO': { code: 'CO', name: 'Colombia',        flag: '🇨🇴', defaultLanguages: ['es'], timezone: 'America/Bogota' },
+  'CL': { code: 'CL', name: 'Chile',           flag: '🇨🇱', defaultLanguages: ['es'], timezone: 'America/Santiago' },
+
+  // Middle East & North Africa
+  'SA': { code: 'SA', name: 'Saudi Arabia',    flag: '🇸🇦', defaultLanguages: ['ar'], timezone: 'Asia/Riyadh' },
+  'AE': { code: 'AE', name: 'United Arab Emirates', flag: '🇦🇪', defaultLanguages: ['ar', 'en'], timezone: 'Asia/Dubai' },
+  'IL': { code: 'IL', name: 'Israel',          flag: '🇮🇱', defaultLanguages: ['he'], timezone: 'Asia/Jerusalem' },
+  'EG': { code: 'EG', name: 'Egypt',           flag: '🇪🇬', defaultLanguages: ['ar'], timezone: 'Africa/Cairo' },
+}
+
+/**
+ * Get a country by its code.
+ */
+export function getCountry(code: string): Country | undefined {
+  return COUNTRIES[code]
+}
+
+/**
+ * Get the flag emoji for a country code.
+ * Returns empty string if the code is not found.
+ */
+export function getCountryFlag(code: string): string {
+  return COUNTRIES[code]?.flag ?? ''
+}
+
+/**
+ * Get the display name for a country code.
+ * Returns empty string if the code is not found.
+ */
+export function getCountryName(code: string): string {
+  return COUNTRIES[code]?.name ?? ''
+}
+
+/**
+ * Get default languages for a country.
+ * Returns empty array if the country is not found.
+ */
+export function getDefaultLanguagesForCountry(code: string): string[] {
+  return COUNTRIES[code]?.defaultLanguages ?? []
+}

package/dist/i18n/detect-region.ts

@@ -0,0 +1,243 @@
+/**
+ * Region detection utilities.
+ * Detects user country and language from browser/environment signals.
+ */
+
+/** Mapping of IANA timezone identifiers to ISO country codes */
+export const TIMEZONE_TO_COUNTRY: Record<string, string> = {
+  // United States
+  'America/New_York': 'US',
+  'America/Chicago': 'US',
+  'America/Denver': 'US',
+  'America/Los_Angeles': 'US',
+  'America/Phoenix': 'US',
+  'America/Anchorage': 'US',
+  'Pacific/Honolulu': 'US',
+  'America/Detroit': 'US',
+  'America/Indiana/Indianapolis': 'US',
+  'America/Boise': 'US',
+
+  // Canada
+  'America/Toronto': 'CA',
+  'America/Vancouver': 'CA',
+  'America/Edmonton': 'CA',
+  'America/Winnipeg': 'CA',
+  'America/Halifax': 'CA',
+  'America/St_Johns': 'CA',
+
+  // Mexico
+  'America/Mexico_City': 'MX',
+  'America/Cancun': 'MX',
+  'America/Tijuana': 'MX',
+
+  // UK & Ireland
+  'Europe/London': 'GB',
+  'Europe/Dublin': 'IE',
+
+  // Western Europe
+  'Europe/Paris': 'FR',
+  'Europe/Berlin': 'DE',
+  'Europe/Madrid': 'ES',
+  'Europe/Rome': 'IT',
+  'Europe/Lisbon': 'PT',
+  'Europe/Amsterdam': 'NL',
+  'Europe/Brussels': 'BE',
+  'Europe/Zurich': 'CH',
+  'Europe/Vienna': 'AT',
+
+  // Nordic
+  'Europe/Stockholm': 'SE',
+  'Europe/Oslo': 'NO',
+  'Europe/Copenhagen': 'DK',
+  'Europe/Helsinki': 'FI',
+
+  // Eastern Europe
+  'Europe/Warsaw': 'PL',
+  'Europe/Prague': 'CZ',
+  'Europe/Bucharest': 'RO',
+  'Europe/Budapest': 'HU',
+  'Europe/Sofia': 'BG',
+  'Europe/Zagreb': 'HR',
+  'Europe/Bratislava': 'SK',
+  'Europe/Ljubljana': 'SI',
+  'Europe/Belgrade': 'RS',
+  'Europe/Kyiv': 'UA',
+  'Europe/Moscow': 'RU',
+  'Europe/Istanbul': 'TR',
+  'Europe/Athens': 'GR',
+
+  // South Asia
+  'Asia/Kolkata': 'IN',
+  'Asia/Calcutta': 'IN',
+  'Asia/Karachi': 'PK',
+  'Asia/Dhaka': 'BD',
+  'Asia/Colombo': 'LK',
+  'Asia/Kathmandu': 'NP',
+
+  // East Asia
+  'Asia/Tokyo': 'JP',
+  'Asia/Seoul': 'KR',
+  'Asia/Shanghai': 'CN',
+  'Asia/Hong_Kong': 'CN',
+  'Asia/Taipei': 'TW',
+
+  // Southeast Asia
+  'Asia/Bangkok': 'TH',
+  'Asia/Ho_Chi_Minh': 'VN',
+  'Asia/Jakarta': 'ID',
+  'Asia/Kuala_Lumpur': 'MY',
+  'Asia/Manila': 'PH',
+  'Asia/Singapore': 'SG',
+
+  // Oceania
+  'Australia/Sydney': 'AU',
+  'Australia/Melbourne': 'AU',
+  'Australia/Brisbane': 'AU',
+  'Australia/Perth': 'AU',
+  'Australia/Adelaide': 'AU',
+  'Pacific/Auckland': 'NZ',
+
+  // South America
+  'America/Sao_Paulo': 'BR',
+  'America/Rio_Branco': 'BR',
+  'America/Argentina/Buenos_Aires': 'AR',
+  'America/Bogota': 'CO',
+  'America/Santiago': 'CL',
+
+  // Middle East
+  'Asia/Riyadh': 'SA',
+  'Asia/Dubai': 'AE',
+  'Asia/Jerusalem': 'IL',
+  'Africa/Cairo': 'EG',
+}
+
+/** Mapping of BCP-47 locale strings to ISO country codes */
+export const LOCALE_TO_COUNTRY: Record<string, string> = {
+  'en-US': 'US',
+  'en-GB': 'GB',
+  'en-AU': 'AU',
+  'en-CA': 'CA',
+  'en-NZ': 'NZ',
+  'en-IE': 'IE',
+  'en-IN': 'IN',
+  'en-SG': 'SG',
+  'en-PH': 'PH',
+  'en-MY': 'MY',
+  'en-ZA': 'ZA',
+  'hi-IN': 'IN',
+  'te-IN': 'IN',
+  'ta-IN': 'IN',
+  'ur-PK': 'PK',
+  'pa-IN': 'IN',
+  'bn-IN': 'IN',
+  'bn-BD': 'BD',
+  'gu-IN': 'IN',
+  'mr-IN': 'IN',
+  'kn-IN': 'IN',
+  'ml-IN': 'IN',
+  'fr-FR': 'FR',
+  'fr-CA': 'CA',
+  'fr-BE': 'BE',
+  'fr-CH': 'CH',
+  'es-ES': 'ES',
+  'es-MX': 'MX',
+  'es-AR': 'AR',
+  'es-CO': 'CO',
+  'es-CL': 'CL',
+  'de-DE': 'DE',
+  'de-AT': 'AT',
+  'de-CH': 'CH',
+  'it-IT': 'IT',
+  'it-CH': 'CH',
+  'pt-PT': 'PT',
+  'pt-BR': 'BR',
+  'nl-NL': 'NL',
+  'nl-BE': 'BE',
+  'sv-SE': 'SE',
+  'da-DK': 'DK',
+  'nb-NO': 'NO',
+  'nn-NO': 'NO',
+  'fi-FI': 'FI',
+  'pl-PL': 'PL',
+  'cs-CZ': 'CZ',
+  'ro-RO': 'RO',
+  'hu-HU': 'HU',
+  'bg-BG': 'BG',
+  'hr-HR': 'HR',
+  'sk-SK': 'SK',
+  'sl-SI': 'SI',
+  'sr-RS': 'SR',
+  'uk-UA': 'UA',
+  'el-GR': 'GR',
+  'ru-RU': 'RU',
+  'ja-JP': 'JP',
+  'ko-KR': 'KR',
+  'zh-CN': 'CN',
+  'zh-TW': 'TW',
+  'zh-HK': 'CN',
+  'ar-SA': 'SA',
+  'ar-AE': 'AE',
+  'ar-EG': 'EG',
+  'he-IL': 'IL',
+  'tr-TR': 'TR',
+  'th-TH': 'TH',
+  'vi-VN': 'VN',
+  'id-ID': 'ID',
+  'ms-MY': 'MY',
+}
+
+/**
+ * Detect the user's country from environment signals.
+ * Strategy: timezone mapping -> navigator.languages locale mapping -> fallback 'US'
+ */
+export function detectCountry(): string {
+  // 1. Try timezone mapping
+  try {
+    const tz = Intl.DateTimeFormat().resolvedOptions().timeZone
+    if (tz && TIMEZONE_TO_COUNTRY[tz]) {
+      return TIMEZONE_TO_COUNTRY[tz]
+    }
+  } catch {
+    // Intl may not be available
+  }
+
+  // 2. Try navigator.languages locale mapping
+  try {
+    if (typeof navigator !== 'undefined') {
+      const languages = navigator.languages
+      if (languages && languages.length > 0) {
+        for (const locale of languages) {
+          if (LOCALE_TO_COUNTRY[locale]) {
+            return LOCALE_TO_COUNTRY[locale]
+          }
+        }
+      }
+    }
+  } catch {
+    // navigator may not be available
+  }
+
+  // 3. Fallback
+  return 'US'
+}
+
+/**
+ * Detect the user's preferred language from navigator.languages.
+ * Returns the first language from navigator.languages, or 'en' as fallback.
+ */
+export function detectLanguage(): string {
+  try {
+    if (typeof navigator !== 'undefined') {
+      const languages = (navigator as any).languages
+      if (languages && languages.length > 0) {
+        return languages[0]
+      }
+      if ((navigator as any).language) {
+        return (navigator as any).language
+      }
+    }
+  } catch {
+    // navigator may not be available
+  }
+  return 'en'
+}