@refraction-ui/astro 0.17.0 → 0.17.2

package/dist/i18n/locale-utils.ts

@@ -0,0 +1,123 @@
+/**
+ * Locale utilities for display names, storage, and localized value resolution.
+ */
+
+/** Display names for common locale codes (in their native language) */
+export const LOCALE_DISPLAY_NAMES: Record<string, string> = {
+  'en': 'English',
+  'en-US': 'English (US)',
+  'en-GB': 'English (UK)',
+  'en-IN': 'English (India)',
+  'hi': 'हिन्दी',
+  'te': 'తెలుగు',
+  'ta': 'தமிழ்',
+  'ur': 'اردو',
+  'pa': 'ਪੰਜਾਬੀ',
+  'bn': 'বাংলা',
+  'gu': 'ગુજરાતી',
+  'mr': 'मराठी',
+  'kn': 'ಕನ್ನಡ',
+  'ml': 'മലയാളം',
+  'fr': 'Français',
+  'es': 'Español',
+  'de': 'Deutsch',
+  'it': 'Italiano',
+  'pt': 'Português',
+  'pt-BR': 'Português (Brasil)',
+  'nl': 'Nederlands',
+  'sv': 'Svenska',
+  'da': 'Dansk',
+  'no': 'Norsk',
+  'fi': 'Suomi',
+  'pl': 'Polski',
+  'cs': 'Čeština',
+  'ro': 'Română',
+  'hu': 'Magyar',
+  'bg': 'Български',
+  'hr': 'Hrvatski',
+  'sk': 'Slovenčina',
+  'sl': 'Slovenščina',
+  'sr': 'Srpski',
+  'uk': 'Українська',
+  'el': 'Ελληνικά',
+  'ru': 'Русский',
+  'ja': '日本語',
+  'ko': '한국어',
+  'zh': '中文',
+  'zh-TW': '中文（繁體）',
+  'ar': 'العربية',
+  'he': 'עברית',
+  'tr': 'Türkçe',
+  'th': 'ไทย',
+  'vi': 'Tiếng Việt',
+  'id': 'Bahasa Indonesia',
+  'ms': 'Bahasa Melayu',
+}
+
+const DEFAULT_STORAGE_KEY = 'refraction-ui-locale'
+
+/**
+ * Get the display name for a locale code.
+ * Returns the code itself if not found in the display names map.
+ */
+export function getLocaleDisplayName(code: string): string {
+  return LOCALE_DISPLAY_NAMES[code] ?? code
+}
+
+/**
+ * Get the stored locale from localStorage (or compatible storage).
+ * Returns null if not stored or localStorage is not available.
+ */
+export function getStoredLocale(storageKey?: string): string | null {
+  try {
+    if (typeof localStorage !== 'undefined') {
+      return localStorage.getItem(storageKey ?? DEFAULT_STORAGE_KEY)
+    }
+  } catch {
+    // localStorage may not be available
+  }
+  return null
+}
+
+/**
+ * Store a locale code in localStorage (or compatible storage).
+ * Does nothing if localStorage is not available.
+ */
+export function setStoredLocale(code: string, storageKey?: string): void {
+  try {
+    if (typeof localStorage !== 'undefined') {
+      localStorage.setItem(storageKey ?? DEFAULT_STORAGE_KEY, code)
+    }
+  } catch {
+    // localStorage may not be available
+  }
+}
+
+/**
+ * Resolve a localized value from a record of locale -> value.
+ * Tries exact locale, then base language code (for regional variants like 'en-US' -> 'en'),
+ * then the fallback locale.
+ */
+export function getLocalizedValue<T>(
+  localized: Record<string, T>,
+  locale: string,
+  fallbackLocale?: string,
+): T | undefined {
+  // 1. Exact match
+  if (locale in localized) {
+    return localized[locale]
+  }
+
+  // 2. Try base language code (e.g., 'en-US' -> 'en')
+  const baseLang = locale.split('-')[0]
+  if (baseLang !== locale && baseLang in localized) {
+    return localized[baseLang]
+  }
+
+  // 3. Fallback locale
+  if (fallbackLocale && fallbackLocale in localized) {
+    return localized[fallbackLocale]
+  }
+
+  return undefined
+}

package/dist/i18n/voice-registry.ts

@@ -0,0 +1,92 @@
+/**
+ * Voice registry for TTS providers.
+ */
+
+export interface VoiceOption {
+  id: string
+  name: string
+  language: string
+  provider: 'browser' | 'google' | 'elevenlabs' | 'openai'
+  gender?: 'male' | 'female'
+}
+
+export const VOICES: VoiceOption[] = [
+  // Browser voices — English
+  { id: 'browser-en-us-female', name: 'English (US) Female', language: 'en-US', provider: 'browser', gender: 'female' },
+  { id: 'browser-en-us-male', name: 'English (US) Male', language: 'en-US', provider: 'browser', gender: 'male' },
+  { id: 'browser-en-gb-female', name: 'English (UK) Female', language: 'en-GB', provider: 'browser', gender: 'female' },
+  { id: 'browser-en-gb-male', name: 'English (UK) Male', language: 'en-GB', provider: 'browser', gender: 'male' },
+  { id: 'browser-en-in-female', name: 'English (India) Female', language: 'en-IN', provider: 'browser', gender: 'female' },
+
+  // Browser voices — European
+  { id: 'browser-fr-female', name: 'French Female', language: 'fr', provider: 'browser', gender: 'female' },
+  { id: 'browser-de-female', name: 'German Female', language: 'de', provider: 'browser', gender: 'female' },
+  { id: 'browser-es-female', name: 'Spanish Female', language: 'es', provider: 'browser', gender: 'female' },
+  { id: 'browser-it-female', name: 'Italian Female', language: 'it', provider: 'browser', gender: 'female' },
+  { id: 'browser-pt-female', name: 'Portuguese Female', language: 'pt', provider: 'browser', gender: 'female' },
+
+  // Browser voices — Asian
+  { id: 'browser-ja-female', name: 'Japanese Female', language: 'ja', provider: 'browser', gender: 'female' },
+  { id: 'browser-ko-female', name: 'Korean Female', language: 'ko', provider: 'browser', gender: 'female' },
+  { id: 'browser-zh-female', name: 'Chinese Female', language: 'zh', provider: 'browser', gender: 'female' },
+  { id: 'browser-hi-female', name: 'Hindi Female', language: 'hi', provider: 'browser', gender: 'female' },
+  { id: 'browser-ar-male', name: 'Arabic Male', language: 'ar', provider: 'browser', gender: 'male' },
+
+  // Google TTS voices
+  { id: 'google-en-us-wavenet-d', name: 'Google WaveNet English (US)', language: 'en-US', provider: 'google', gender: 'male' },
+  { id: 'google-en-us-wavenet-f', name: 'Google WaveNet English (US) Female', language: 'en-US', provider: 'google', gender: 'female' },
+  { id: 'google-en-gb-wavenet-a', name: 'Google WaveNet English (UK)', language: 'en-GB', provider: 'google', gender: 'female' },
+  { id: 'google-fr-wavenet-a', name: 'Google WaveNet French', language: 'fr', provider: 'google', gender: 'female' },
+  { id: 'google-de-wavenet-a', name: 'Google WaveNet German', language: 'de', provider: 'google', gender: 'female' },
+  { id: 'google-es-wavenet-a', name: 'Google WaveNet Spanish', language: 'es', provider: 'google', gender: 'female' },
+  { id: 'google-ja-wavenet-a', name: 'Google WaveNet Japanese', language: 'ja', provider: 'google', gender: 'female' },
+  { id: 'google-hi-wavenet-a', name: 'Google WaveNet Hindi', language: 'hi', provider: 'google', gender: 'female' },
+  { id: 'google-ar-wavenet-a', name: 'Google WaveNet Arabic', language: 'ar', provider: 'google', gender: 'female' },
+
+  // ElevenLabs voices
+  { id: 'elevenlabs-rachel', name: 'Rachel', language: 'en', provider: 'elevenlabs', gender: 'female' },
+  { id: 'elevenlabs-adam', name: 'Adam', language: 'en', provider: 'elevenlabs', gender: 'male' },
+  { id: 'elevenlabs-antoni', name: 'Antoni', language: 'en', provider: 'elevenlabs', gender: 'male' },
+  { id: 'elevenlabs-bella', name: 'Bella', language: 'es', provider: 'elevenlabs', gender: 'female' },
+  { id: 'elevenlabs-elli', name: 'Elli', language: 'de', provider: 'elevenlabs', gender: 'female' },
+
+  // OpenAI TTS voices
+  { id: 'openai-alloy', name: 'Alloy', language: 'en', provider: 'openai' },
+  { id: 'openai-echo', name: 'Echo', language: 'en', provider: 'openai', gender: 'male' },
+  { id: 'openai-fable', name: 'Fable', language: 'en', provider: 'openai', gender: 'male' },
+  { id: 'openai-onyx', name: 'Onyx', language: 'en', provider: 'openai', gender: 'male' },
+  { id: 'openai-nova', name: 'Nova', language: 'en', provider: 'openai', gender: 'female' },
+  { id: 'openai-shimmer', name: 'Shimmer', language: 'en', provider: 'openai', gender: 'female' },
+]
+
+/**
+ * Get all voices that match a given language code.
+ * Matches both exact codes and prefix codes (e.g., 'en' matches 'en', 'en-US', 'en-GB').
+ */
+export function getVoicesForLanguage(langCode: string): VoiceOption[] {
+  return VOICES.filter((v) => v.language === langCode || v.language.startsWith(langCode + '-') || langCode.startsWith(v.language + '-') || v.language.split('-')[0] === langCode)
+}
+
+/**
+ * Get the best voice for a language, optionally preferring a specific provider.
+ * Returns undefined if no voice matches.
+ */
+export function getBestVoice(langCode: string, preferredProvider?: VoiceOption['provider']): VoiceOption | undefined {
+  const voices = getVoicesForLanguage(langCode)
+  if (voices.length === 0) return undefined
+
+  if (preferredProvider) {
+    const preferred = voices.find((v) => v.provider === preferredProvider)
+    if (preferred) return preferred
+  }
+
+  // Return first available voice
+  return voices[0]
+}
+
+/**
+ * Get all voices from a specific provider.
+ */
+export function getVoicesByProvider(provider: VoiceOption['provider']): VoiceOption[] {
+  return VOICES.filter((v) => v.provider === provider)
+}

package/dist/index.ts

@@ -64,6 +64,7 @@ export * from './astro-link-card/index.ts';
 export * from './astro-live-captions/index.ts';
 export * from './astro-live-cursors/index.ts';
 export * from './astro-live-transcript/index.ts';
+export * from './astro-location-selector/index.ts';
 export * from './astro-logger/index.ts';
 export * from './astro-markdown-renderer/index.ts';
 export * from './astro-marquee-strip/index.ts';

package/dist/location-selector/index.ts

@@ -0,0 +1 @@
+export * from './location-selector.ts'

package/dist/location-selector/location-selector.ts

@@ -0,0 +1,60 @@
+import { COUNTRIES, LANGUAGES, detectCountry, detectLanguage } from '../i18n/index.ts'
+import { generateId } from '../shared/index.ts'
+
+export interface LocationSelectorState {
+  country: string
+  language: string
+}
+
+export interface LocationSelectorOptions {
+  defaultCountry?: string
+  defaultLanguage?: string
+  onCountryChange?: (country: string) => void
+  onLanguageChange?: (language: string) => void
+}
+
+export function createLocationSelector(options: LocationSelectorOptions = {}) {
+  const {
+    defaultCountry = 'US',
+    defaultLanguage = 'en',
+    onCountryChange,
+    onLanguageChange,
+  } = options
+
+  let state: LocationSelectorState = {
+    country: defaultCountry,
+    language: defaultLanguage,
+  }
+
+  const countryId = generateId('location-sel-country')
+  const languageId = generateId('location-sel-language')
+
+  function setCountry(country: string) {
+    state.country = country
+    onCountryChange?.(country)
+  }
+
+  function setLanguage(language: string) {
+    state.language = language
+    onLanguageChange?.(language)
+  }
+
+  const countries = Array.isArray(COUNTRIES) ? COUNTRIES : Object.values(COUNTRIES)
+  const languages = Array.isArray(LANGUAGES) ? LANGUAGES : Object.values(LANGUAGES)
+
+  return {
+    state,
+    setCountry,
+    setLanguage,
+    countries,
+    languages,
+    countryProps: {
+      id: countryId,
+      name: 'country',
+    },
+    languageProps: {
+      id: languageId,
+      name: 'language',
+    },
+  }
+}

package/dist/logger/telemetry-manager.ts

@@ -34,6 +34,9 @@ export function createTelemetry(config: TelemetryConfig): Telemetry {
   const preset = resolvePreset(config.env)
   const sampleRate = config.sampleRate ?? preset.sampleRate
   const redactKeys = config.redactKeys ?? []
+  // Injection boundary: ambient time/randomness default here; inject `now`/`random` for determinism.
+  const now = config.now ?? (() => Date.now())
+  const random = config.random ?? (() => Math.random())
 
   const sinks = new Map<string, TelemetrySink>()
   /** Insertion-ordered sink names. */
@@ -71,7 +74,7 @@ export function createTelemetry(config: TelemetryConfig): Telemetry {
   function shouldSample(): boolean {
     if (sampleRate >= 1) return true
     if (sampleRate <= 0) return false
-    return Math.random() < sampleRate
+    return random() < sampleRate
   }
 
   function dispatch(
@@ -134,7 +137,7 @@ export function createTelemetry(config: TelemetryConfig): Telemetry {
       const record: LogRecord = {
         level,
         message,
-        timestamp: Date.now(),
+        timestamp: now(),
         app: config.app,
         env: config.env,
         context: merged,
@@ -164,13 +167,13 @@ export function createTelemetry(config: TelemetryConfig): Telemetry {
       },
 
       startSpan(name: string, attributes?: LogContext): Span {
-        const startTime = Date.now()
+        const startTime = now()
         let ended = false
         return {
           end(opts?: { error?: unknown; attributes?: LogContext }): void {
             if (ended) return
             ended = true
-            const endTime = Date.now()
+            const endTime = now()
             const merged = redact(
               { ...boundContext, ...attributes, ...opts?.attributes },
               redactKeys,

package/dist/logger/types.ts

@@ -84,6 +84,10 @@ export interface TelemetryConfig {
    * PII / secrets, e.g. `['password', 'token', 'authorization']`.
    */
   redactKeys?: string[]
+  /** Clock for record timestamps and span timing (ms epoch). Default: ambient `Date.now()` — inject for deterministic tests. */
+  now?: () => number
+  /** RNG for sample-rate decisions. Default: ambient `Math.random` — inject for deterministic tests. */
+  random?: () => number
 }
 
 /** A logger bound to a context. Child loggers inherit + extend that context. */

package/dist/pagination/index.ts

@@ -1 +1,14 @@
-export {}
+export {
+  createPagination,
+  clampPage,
+  getPaginationItems,
+  type PaginationItem,
+  type PaginationConfig,
+  type PaginationAPI,
+} from './pagination.js'
+
+export {
+  paginationVariants,
+  paginationItemVariants,
+  paginationEllipsisClass,
+} from './pagination.styles.js'

package/dist/pagination/pagination.styles.ts

@@ -0,0 +1,33 @@
+import { cva } from '../shared/index.ts'
+
+/** Row of pagination controls. */
+export const paginationVariants = cva({
+  base: 'flex items-center gap-1',
+})
+
+/**
+ * A pagination button (prev / next / numbered page). The `state` variant
+ * carries the current-page treatment so adapters never inline these classes.
+ */
+export const paginationItemVariants = cva({
+  base: [
+    'inline-flex h-9 min-w-9 items-center justify-center rounded-md border px-3',
+    'text-sm font-medium transition-colors',
+    'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+    'focus-visible:ring-offset-2 focus-visible:ring-offset-background',
+    'disabled:pointer-events-none disabled:opacity-50',
+  ].join(' '),
+  variants: {
+    state: {
+      current: 'border-primary bg-primary text-primary-foreground',
+      default: 'border-border bg-background text-foreground hover:bg-muted',
+    },
+  },
+  defaultVariants: {
+    state: 'default',
+  },
+})
+
+/** Ellipsis gap between page numbers (not interactive). */
+export const paginationEllipsisClass =
+  'inline-flex h-9 min-w-9 items-center justify-center text-sm text-muted-foreground'

package/dist/pagination/pagination.ts

@@ -0,0 +1,160 @@
+/**
+ * @refraction-ui/pagination — headless pagination.
+ *
+ * Owns the *behavior* of page navigation: the windowed page range with
+ * ellipses, current-page clamping, and prev/next edge semantics. It has NO UI
+ * opinion — adapters render the controls and spread the ARIA objects.
+ */
+
+/** One entry of the computed page range: a page number or an ellipsis gap. */
+export type PaginationItem =
+  | { type: 'page'; page: number }
+  | { type: 'ellipsis'; id: 'start' | 'end' }
+
+/** Options for {@link createPagination}. */
+export interface PaginationConfig {
+  /** Current page (1-based). Clamped into `[1, totalPages]`. */
+  page?: number
+  /** Total number of pages. Values < 1 behave as 1. */
+  totalPages?: number
+  /** Pages shown on each side of the current page (default 1). */
+  siblingCount?: number
+  /** Accessible label for the nav landmark (default `'Pagination'`). */
+  ariaLabel?: string
+}
+
+/** The computed view of a pagination control. */
+export interface PaginationAPI {
+  /** ARIA attributes for the root element (`role="navigation"`). */
+  ariaProps: Record<string, string | number | boolean>
+  /** Data attributes for styling hooks. */
+  dataAttributes: Record<string, string>
+  /** Current page after clamping (1-based). */
+  page: number
+  /** Total number of pages (>= 1). */
+  totalPages: number
+  /** Windowed range of pages and ellipses to render. */
+  items: PaginationItem[]
+  /** Whether "previous" navigation is possible. */
+  canGoPrevious: boolean
+  /** Whether "next" navigation is possible. */
+  canGoNext: boolean
+  /** Target page for the previous control (clamped). */
+  previousPage: number
+  /** Target page for the next control (clamped). */
+  nextPage: number
+  /** ARIA attributes for a numbered page button (`aria-current` on the current page). */
+  getPageAria(page: number): Record<string, string | number | boolean>
+  /** ARIA attributes for the previous control. */
+  getPreviousAria(): Record<string, string | number | boolean>
+  /** ARIA attributes for the next control. */
+  getNextAria(): Record<string, string | number | boolean>
+}
+
+/** Clamp a 1-based page number into `[1, max(totalPages, 1)]`. */
+export function clampPage(page: number, totalPages: number): number {
+  const total = Math.max(1, Math.floor(totalPages))
+  if (Number.isNaN(page)) return 1
+  return Math.min(Math.max(1, Math.floor(page)), total)
+}
+
+function pageItem(page: number): PaginationItem {
+  return { type: 'page', page }
+}
+
+function pageRange(start: number, end: number): PaginationItem[] {
+  const items: PaginationItem[] = []
+  for (let p = start; p <= end; p++) items.push(pageItem(p))
+  return items
+}
+
+/**
+ * Compute the windowed page range with ellipses.
+ *
+ * Always shows the first and last page plus `siblingCount` pages on each side
+ * of the current page; gaps of more than one page collapse into an ellipsis.
+ * Small totals render every page (no ellipses).
+ */
+export function getPaginationItems(
+  current: number,
+  totalPages: number,
+  siblingCount = 1,
+): PaginationItem[] {
+  const total = Math.max(0, Math.floor(totalPages))
+  if (total === 0) return []
+
+  // first + last + current + 2 siblings + 2 ellipses
+  const maxVisibleWithoutEllipsis = siblingCount * 2 + 5
+  if (total <= maxVisibleWithoutEllipsis) return pageRange(1, total)
+
+  const currentPage = clampPage(current, total)
+  const leftSibling = Math.max(currentPage - siblingCount, 1)
+  const rightSibling = Math.min(currentPage + siblingCount, total)
+
+  const showLeftEllipsis = leftSibling > 2
+  const showRightEllipsis = rightSibling < total - 1
+
+  if (!showLeftEllipsis && showRightEllipsis) {
+    const leftCount = 3 + 2 * siblingCount
+    return [...pageRange(1, leftCount), { type: 'ellipsis', id: 'end' }, pageItem(total)]
+  }
+
+  if (showLeftEllipsis && !showRightEllipsis) {
+    const rightCount = 3 + 2 * siblingCount
+    return [
+      pageItem(1),
+      { type: 'ellipsis', id: 'start' },
+      ...pageRange(total - rightCount + 1, total),
+    ]
+  }
+
+  return [
+    pageItem(1),
+    { type: 'ellipsis', id: 'start' },
+    ...pageRange(leftSibling, rightSibling),
+    { type: 'ellipsis', id: 'end' },
+    pageItem(total),
+  ]
+}
+
+/**
+ * createPagination — the framework-agnostic view of a pagination control:
+ * ARIA objects for the nav landmark and controls, plus the clamped
+ * current/total and prev/next edge semantics. Adapters own the page state
+ * (controlled/uncontrolled) and call this per render.
+ */
+export function createPagination(config: PaginationConfig = {}): PaginationAPI {
+  const totalPages = Math.max(1, Math.floor(config.totalPages ?? 1))
+  const page = clampPage(config.page ?? 1, totalPages)
+  const siblingCount = Math.max(0, Math.floor(config.siblingCount ?? 1))
+
+  const canGoPrevious = page > 1
+  const canGoNext = page < totalPages
+
+  return {
+    ariaProps: {
+      role: 'navigation',
+      'aria-label': config.ariaLabel ?? 'Pagination',
+    },
+    dataAttributes: {
+      'data-page': String(page),
+      'data-total-pages': String(totalPages),
+    },
+    page,
+    totalPages,
+    items: getPaginationItems(page, totalPages, siblingCount),
+    canGoPrevious,
+    canGoNext,
+    previousPage: canGoPrevious ? page - 1 : page,
+    nextPage: canGoNext ? page + 1 : page,
+    getPageAria(p): Record<string, string | number | boolean> {
+      return p === page ? { 'aria-current': 'page' } : {}
+    },
+    getPreviousAria(): Record<string, string | number | boolean> {
+      return { 'aria-label': 'Previous page' }
+    },
+    getNextAria(): Record<string, string | number | boolean> {
+      return { 'aria-label': 'Next page' }
+    },
+  }
+}

package/dist/presence-indicator/presence-indicator.ts

@@ -1,5 +1,3 @@
-import type { AccessibilityProps } from '../shared/index.ts'
-
 export type PresenceStatus = 'online' | 'offline' | 'away' | 'busy' | 'dnd'
 
 export interface PresenceProps {
@@ -13,7 +11,7 @@ export interface PresenceProps {
 
 export interface PresenceAPI {
   /** ARIA attributes for the indicator */
-  ariaProps: Partial<AccessibilityProps> & Record<string, unknown>
+  ariaProps: Record<string, string | number | boolean>
   /** CSS color for the status dot */
   color: string
   /** Human-readable label for the status */
@@ -48,7 +46,7 @@ export function createPresence(props: PresenceProps): PresenceAPI {
   const color = STATUS_COLORS[status]
   const label = labelOverride ?? STATUS_LABELS[status]
 
-  const ariaProps: Partial<AccessibilityProps> & Record<string, unknown> = {
+  const ariaProps: Record<string, string | number | boolean> = {
     role: 'status',
     'aria-label': label,
   }

package/dist/reaction-bar/reaction-bar.ts

@@ -1,4 +1,3 @@
-import type { AccessibilityProps } from '../shared/index.ts'
 import { generateId } from '../shared/index.ts'
 
 export interface Reaction {
@@ -27,7 +26,7 @@ export interface ReactionBarAPI {
   /** Add a new reaction */
   add(emoji: string): void
   /** ARIA props for the reaction bar container */
-  ariaProps: Partial<AccessibilityProps> & Record<string, unknown>
+  ariaProps: Record<string, string | number | boolean>
   /** Get ARIA props for an individual reaction pill */
   getReactionAriaProps(reaction: Reaction): Record<string, unknown>
   /** ARIA props for the "add reaction" button */
@@ -53,7 +52,7 @@ export function createReactionBar(props: ReactionBarProps): ReactionBarAPI {
     onAdd?.(emoji)
   }
 
-  const ariaProps: Partial<AccessibilityProps> & Record<string, unknown> = {
+  const ariaProps: Record<string, string | number | boolean> = {
     role: 'group',
     'aria-label': 'Reactions',
     id: containerId,