@refraction-ui/astro 0.17.1 → 0.17.2

package/dist/accordion/accordion.ts

@@ -0,0 +1,155 @@
+/**
+ * @refraction-ui/accordion — headless accordion (disclosure) state machine.
+ *
+ * Owns the *behavior* of an accordion: which item(s) are open, the single vs
+ * multiple expansion modes, and the collapsible toggle rule. It has NO UI
+ * opinion — React/Astro adapters subscribe to the store and render the parts.
+ */
+
+/** Expansion mode: one item open at a time, or any number. */
+export type AccordionType = 'single' | 'multiple'
+
+/** Open item id (`single`) or ids (`multiple`). */
+export type AccordionValue = string | string[]
+
+/** Options for {@link createAccordion}. */
+export interface AccordionConfig {
+  /** Expansion mode (default `'single'`). */
+  type?: AccordionType
+  /** When `type="single"`, allows the open item to be toggled fully closed. */
+  collapsible?: boolean
+  /** Controlled open item(s). Pair with `onValueChange`. */
+  value?: AccordionValue
+  /** Uncontrolled initial open item(s). */
+  defaultValue?: AccordionValue
+  /** Called whenever the open item(s) change. */
+  onValueChange?: (value: AccordionValue) => void
+}
+
+/** Snapshot of the store. Returned by `getState()`; treat as immutable. */
+export interface AccordionState {
+  type: AccordionType
+  collapsible: boolean
+  /** Current open item id (`single`) or ids (`multiple`). */
+  value: AccordionValue
+}
+
+/** The framework-agnostic store. React/Astro adapters wrap this. */
+export interface AccordionAPI {
+  /** Current immutable snapshot */
+  getState(): AccordionState
+  /** Subscribe to changes; returns an unsubscribe fn (suits useSyncExternalStore) */
+  subscribe(listener: () => void): () => void
+  /** Toggle an item open/closed per the type/collapsible rules */
+  toggleItem(itemValue: string): void
+  /** Whether an item is currently open */
+  isOpen(itemValue: string): boolean
+  /** Sync a controlled value into the store (adapters call when the prop changes) */
+  setValue(value: AccordionValue): void
+  /** Update options after creation (adapters keep props in sync) */
+  setOptions(options: {
+    type?: AccordionType
+    collapsible?: boolean
+    onValueChange?: (value: AccordionValue) => void
+  }): void
+}
+
+/** Pure open-state check shared by every adapter. */
+export function isItemOpen(state: AccordionState, itemValue: string): boolean {
+  return state.type === 'single'
+    ? state.value === itemValue
+    : Array.isArray(state.value) && state.value.includes(itemValue)
+}
+
+/** Shallow value equality (arrays compared item-by-item, order-sensitive). */
+function valueEquals(a: AccordionValue, b: AccordionValue): boolean {
+  if (Array.isArray(a) && Array.isArray(b)) {
+    return a.length === b.length && a.every((v, i) => v === b[i])
+  }
+  return a === b
+}
+
+/**
+ * createAccordion — headless accordion store.
+ *
+ * Supports controlled (`value`) and uncontrolled (`defaultValue`) usage.
+ * `single` mode holds one open item id (`''` when all closed); `multiple`
+ * holds an array of open ids. In `single` mode, re-toggling the open item
+ * closes it only when `collapsible` is set.
+ */
+export function createAccordion(config: AccordionConfig = {}): AccordionAPI {
+  let type: AccordionType = config.type ?? 'single'
+  let collapsible: boolean = config.collapsible ?? false
+  let onValueChange = config.onValueChange
+
+  let uncontrolledValue: AccordionValue =
+    config.defaultValue ?? (type === 'multiple' ? [] : '')
+  let controlledValue: AccordionValue | undefined = config.value
+
+  const listeners = new Set<() => void>()
+  let snapshot: AccordionState = buildSnapshot()
+
+  function currentValue(): AccordionValue {
+    return controlledValue !== undefined ? controlledValue : uncontrolledValue
+  }
+
+  function buildSnapshot(): AccordionState {
+    return { type, collapsible, value: currentValue() }
+  }
+
+  function emit(): void {
+    snapshot = buildSnapshot()
+    for (const l of listeners) l()
+  }
+
+  const api: AccordionAPI = {
+    getState() {
+      return snapshot
+    },
+
+    subscribe(listener) {
+      listeners.add(listener)
+      return () => listeners.delete(listener)
+    },
+
+    toggleItem(itemValue) {
+      const value = currentValue()
+      let next: AccordionValue
+      if (type === 'single') {
+        next = value === itemValue && collapsible ? '' : itemValue
+      } else {
+        const arrValue = Array.isArray(value) ? value : []
+        next = arrValue.includes(itemValue)
+          ? arrValue.filter((v) => v !== itemValue)
+          : [...arrValue, itemValue]
+      }
+      if (controlledValue === undefined) {
+        if (valueEquals(uncontrolledValue, next)) return
+        uncontrolledValue = next
+      }
+      onValueChange?.(next)
+      emit()
+    },
+
+    isOpen(itemValue) {
+      return isItemOpen(snapshot, itemValue)
+    },
+
+    setValue(value) {
+      if (controlledValue !== undefined && valueEquals(controlledValue, value)) return
+      controlledValue = value
+      emit()
+    },
+
+    setOptions(options) {
+      const prevType = type
+      const prevCollapsible = collapsible
+      if (options.type !== undefined) type = options.type
+      if (options.collapsible !== undefined) collapsible = options.collapsible
+      if (options.onValueChange !== undefined) onValueChange = options.onValueChange
+      if (type !== prevType || collapsible !== prevCollapsible) emit()
+    },
+  }
+
+  return api
+}

package/dist/accordion/index.ts

@@ -1 +1,9 @@
-export {}
+export { createAccordion, isItemOpen } from './accordion.js'
+
+export type {
+  AccordionType,
+  AccordionValue,
+  AccordionConfig,
+  AccordionState,
+  AccordionAPI,
+} from './accordion.js'

package/dist/analytics/analytics-manager.ts

@@ -64,6 +64,9 @@ export function createAnalytics(config: AnalyticsConfig): Analytics {
   const sampleRate = config.sampleRate ?? 1
   const batchSize = config.batchSize ?? 20
   const flushIntervalMs = config.flushIntervalMs ?? 10_000
+  // Injection boundary: ambient time/randomness default here; inject `now`/`random` for determinism.
+  const now = config.now ?? (() => new Date())
+  const random = config.random ?? (() => Math.random())
 
   const session = createSession(config.session)
   const identity = createIdentity(config.identity)
@@ -86,6 +89,8 @@ export function createAnalytics(config: AnalyticsConfig): Analytics {
       createHttpSink({
         endpoint: config.endpoint,
         writeKey: config.writeKey ?? '',
+        // One clock for the whole manager: the auto sink stamps sentAt with it too.
+        now,
       }),
     )
   }
@@ -203,7 +208,7 @@ export function createAnalytics(config: AnalyticsConfig): Analytics {
   function sampled(): boolean {
     if (sampleRate >= 1) return true
     if (sampleRate <= 0) return false
-    return Math.random() < sampleRate
+    return random() < sampleRate
   }
 
   function enqueue(ev: AnalyticsEvent): void {
@@ -238,7 +243,7 @@ export function createAnalytics(config: AnalyticsConfig): Analytics {
       userId: identity.userId(),
       sessionId,
       context: buildContext(opts?.context, childCtx),
-      timestamp: opts?.timestamp ?? new Date().toISOString(),
+      timestamp: opts?.timestamp ?? now().toISOString(),
       schemaVersion: SCHEMA_VERSION,
       ...fields,
     }

package/dist/analytics/http-sink.ts

@@ -113,6 +113,8 @@ export function createHttpSink(options: HttpSinkOptions): AnalyticsSink {
   const base = endpoint.replace(/\/+$/, '')
   const url = `${base}/v${SCHEMA_VERSION}/batch`
   const authHeader = `Basic ${base64(`${writeKey}:`)}`
+  // Injection boundary: `sentAt` defaults to ambient time; inject `now` for determinism.
+  const now = options.now ?? (() => new Date())
 
   const resolveFetch = (): typeof fetch => {
     if (options.fetchImpl) return options.fetchImpl
@@ -137,7 +139,7 @@ export function createHttpSink(options: HttpSinkOptions): AnalyticsSink {
   function envelope(batch: AnalyticsEvent[]) {
     return {
       batch,
-      sentAt: new Date().toISOString(),
+      sentAt: now().toISOString(),
       batchId: uuidv4(),
     }
   }

package/dist/analytics/types.ts

@@ -187,6 +187,8 @@ export interface HttpSinkOptions {
   maxBatchBytes?: number
   /** Soft per-event byte cap (Segment ≈ 32KB). Default 32_000. */
   maxEventBytes?: number
+  /** Clock for the batch `sentAt` stamp. Default: ambient `new Date()` — inject for deterministic tests. */
+  now?: () => Date
 }
 
 /** `createAnalytics` configuration. */
@@ -222,6 +224,10 @@ export interface AnalyticsConfig {
   batchSize?: number
   /** Auto-flush interval in ms (prod). Default 10_000. */
   flushIntervalMs?: number
+  /** Clock for default event timestamps. Default: ambient `new Date()` — inject for deterministic tests/SSR. */
+  now?: () => Date
+  /** RNG for sample-rate decisions. Default: ambient `Math.random` — inject for deterministic tests. */
+  random?: () => number
 }
 
 /** Options accepted by every top-level call. */

package/dist/calendar/calendar.ts

@@ -18,6 +18,8 @@ export interface CalendarProps {
   maxDate?: Date
   /** Specific dates to disable */
   disabledDates?: Date[]
+  /** Reference "today" for isToday/aria-current. Default: ambient `new Date()` — inject to avoid SSR/CSR hydration mismatch. */
+  today?: Date
 }
 
 export interface CalendarDay {
@@ -52,9 +54,9 @@ export interface CalendarAPI {
   /** Select a date */
   select(date: Date): void
   /** ARIA attributes for the calendar grid */
-  ariaProps: Partial<AccessibilityProps> & Record<string, unknown>
+  ariaProps: Partial<AccessibilityProps> & Record<string, string | number | boolean>
   /** Get ARIA attributes for a specific day cell */
-  getDayAriaProps(day: CalendarDay): Partial<AccessibilityProps> & Record<string, unknown>
+  getDayAriaProps(day: CalendarDay): Partial<AccessibilityProps> & Record<string, string | number | boolean>
   /** Generated IDs */
   ids: {
     grid: string
@@ -89,9 +91,11 @@ export function createCalendar(props: CalendarProps = {}): CalendarAPI {
     minDate,
     maxDate,
     disabledDates = [],
+    today: injectedToday,
   } = props
 
-  const today = new Date()
+  // Injection boundary: ambient "today" is the default; inject `today` so SSR and client agree.
+  const today = injectedToday ?? new Date()
 
   // Determine selected date
   const selectedDate = controlledValue ?? defaultValue
@@ -167,18 +171,19 @@ export function createCalendar(props: CalendarProps = {}): CalendarAPI {
     }
   }
 
-  const ariaProps: Partial<AccessibilityProps> & Record<string, unknown> = {
+  const ariaProps: Partial<AccessibilityProps> & Record<string, string | number | boolean> = {
     role: 'grid',
     'aria-labelledby': labelId,
     id: gridId,
   }
 
-  function getDayAriaProps(day: CalendarDay): Partial<AccessibilityProps> & Record<string, unknown> {
+  function getDayAriaProps(day: CalendarDay): Partial<AccessibilityProps> & Record<string, string | number | boolean> {
     return {
       role: 'gridcell',
       'aria-selected': day.isSelected,
       'aria-disabled': day.isDisabled,
-      'aria-current': day.isToday ? ('date' as const) : undefined,
+      // Key absent (not undefined) when not today — the ARIA record type excludes undefined.
+      ...(day.isToday ? { 'aria-current': 'date' as const } : {}),
       'aria-label': `${DAY_NAMES[day.date.getDay()]}, ${day.date.toLocaleDateString('en-US', { month: 'long', day: 'numeric', year: 'numeric' })}`,
     }
   }

package/dist/call-controls/call-controls.ts

@@ -1,5 +1,3 @@
-import type { AccessibilityProps } from '../shared/index.ts'
-
 /** Visual/semantic tone of a call control button. */
 export type CallControlTone = 'default' | 'active' | 'destructive'
 
@@ -33,7 +31,7 @@ export interface CallControlsProps {
 
 export interface CallControlsAPI {
   /** ARIA attributes to spread on the toolbar element (`role="toolbar"`). */
-  ariaProps: Partial<AccessibilityProps>
+  ariaProps: Record<string, string | number | boolean>
   /** Data attributes for styling hooks. */
   dataAttributes: Record<string, string>
 }
@@ -66,7 +64,7 @@ export function controlTone(
  * attributes; adapters spread these onto their container element.
  */
 export function createCallControls(_props: CallControlsProps = {}): CallControlsAPI {
-  const ariaProps: Partial<AccessibilityProps> = {
+  const ariaProps: Record<string, string | number | boolean> = {
     role: 'toolbar',
     'aria-label': 'Call controls',
   }

package/dist/carousel/carousel.ts

@@ -0,0 +1,45 @@
+/**
+ * @refraction-ui/carousel — headless "carousel" store.
+ *
+ * Honest note: despite the name, this component is an expand/collapse panel
+ * set (an accordion in disguise) — that is the behavior the React adapter and
+ * the docs site demo (single/multiple open panels, collapsible toggles). The
+ * state machine is therefore shared with `@refraction-ui/accordion` rather
+ * than duplicated. A real slide-navigation carousel (active index, next/prev)
+ * would be a different core; this package keeps the shipped behavior.
+ */
+import {
+  createAccordion,
+  isItemOpen,
+  type AccordionAPI,
+  type AccordionConfig,
+  type AccordionState,
+  type AccordionType,
+  type AccordionValue,
+} from '../accordion/index.ts'
+
+/** Expansion mode: one item open at a time, or any number. */
+export type CarouselType = AccordionType
+
+/** Open item id (`single`) or ids (`multiple`). */
+export type CarouselValue = AccordionValue
+
+/** Options for {@link createCarousel}. Mirrors {@link AccordionConfig}. */
+export interface CarouselConfig extends AccordionConfig {}
+
+/** Snapshot of the store. Returned by `getState()`; treat as immutable. */
+export interface CarouselState extends AccordionState {}
+
+/** The framework-agnostic store. React/Astro adapters wrap this. */
+export type CarouselAPI = AccordionAPI
+
+/**
+ * createCarousel — headless expand/collapse panel store. This is the
+ * accordion state machine under the carousel name; see the package note.
+ */
+export function createCarousel(config: CarouselConfig = {}): CarouselAPI {
+  return createAccordion(config)
+}
+
+/** Pure open-state check shared by every adapter. */
+export { isItemOpen }

package/dist/carousel/index.ts

@@ -1 +1,9 @@
-export {}
+export { createCarousel, isItemOpen } from './carousel.js'
+
+export type {
+  CarouselType,
+  CarouselValue,
+  CarouselConfig,
+  CarouselState,
+  CarouselAPI,
+} from './carousel.js'

package/dist/conversation/conversation.ts

@@ -33,6 +33,8 @@ export function createConversation(config: ConversationConfig = {}): Conversatio
   const assistant = config.assistant ?? DEFAULT_ASSISTANT
   const currentUser = config.currentUser ?? DEFAULT_USER
   const generateTitle = config.generateTitle ?? defaultGenerateTitle
+  // Injection boundary: ambient time is the default; inject `now` for deterministic timestamps.
+  const now = config.now ?? (() => new Date())
 
   let transport = config.transport
   let threadingMode: ThreadingMode = config.threadingMode ?? 'inline'
@@ -87,7 +89,7 @@ export function createConversation(config: ConversationConfig = {}): Conversatio
 
   function touch(conversationId: string): void {
     const c = conversations.get(conversationId)
-    if (c) conversations.set(conversationId, { ...c, updatedAt: new Date() })
+    if (c) conversations.set(conversationId, { ...c, updatedAt: now() })
   }
 
   function ensureActiveConversation(opts?: SendOptions): string {
@@ -103,12 +105,12 @@ export function createConversation(config: ConversationConfig = {}): Conversatio
     opts: { title?: string; metadata?: Record<string, unknown> },
     id?: string,
   ): Conversation {
-    const now = new Date()
+    const timestamp = now()
     const conversation: Conversation = {
       id: id ?? generateId('rfr-conv'),
       title: opts.title ?? DEFAULT_TITLE,
-      createdAt: now,
-      updatedAt: now,
+      createdAt: timestamp,
+      updatedAt: timestamp,
       metadata: opts.metadata,
     }
     conversations.set(conversation.id, conversation)
@@ -294,7 +296,7 @@ export function createConversation(config: ConversationConfig = {}): Conversatio
         role: 'user',
         author: currentUser,
         content: trimmed,
-        timestamp: new Date(),
+        timestamp: now(),
         status: 'sent',
         parentId,
         replyToId,
@@ -323,7 +325,7 @@ export function createConversation(config: ConversationConfig = {}): Conversatio
         role: 'assistant',
         author: assistant,
         content: '',
-        timestamp: new Date(),
+        timestamp: now(),
         status: 'streaming',
         parentId,
       }
@@ -350,7 +352,7 @@ export function createConversation(config: ConversationConfig = {}): Conversatio
         role: 'assistant',
         author: assistant,
         content: '',
-        timestamp: new Date(),
+        timestamp: now(),
         status: 'streaming',
         parentId,
       }

package/dist/conversation/types.ts

@@ -170,6 +170,8 @@ export interface ConversationConfig {
   generateTitle?: (firstMessage: string) => string
   /** Threading mode (default 'inline') */
   threadingMode?: ThreadingMode
+  /** Clock for conversation/message timestamps. Default: ambient `new Date()` — inject for deterministic SSR/tests. */
+  now?: () => Date
 }
 
 /** Options for a single `sendMessage`. */

package/dist/date-picker/date-picker.ts

@@ -26,6 +26,8 @@ export interface DatePickerProps {
   onOpenChange?: (open: boolean) => void
   /** The currently displayed month (controlled) */
   currentMonth?: Date
+  /** Reference "today" for isToday/aria-current and time defaults. Default: ambient `new Date()` — inject to avoid SSR/CSR hydration mismatch. */
+  today?: Date
 }
 
 export interface DatePickerState {
@@ -149,7 +151,8 @@ export function createDatePicker(props: DatePickerProps = {}): DatePickerAPI {
     onOpenChange,
   } = props
 
-  const today = new Date()
+  // Injection boundary: ambient "today" is the default; inject `today` so SSR and client agree.
+  const today = props.today ?? new Date()
   let internalOpen = controlledOpen ?? defaultOpen
   let currentMonth = props.currentMonth ?? (value ? startOfMonth(value) : startOfMonth(today))
   let view: DatePickerView = 'calendar'
@@ -230,14 +233,14 @@ export function createDatePicker(props: DatePickerProps = {}): DatePickerAPI {
 
   function setHours(h: number): void {
     if (h < 0 || h > 23) return
-    const newDate = value ? new Date(value) : new Date()
+    const newDate = value ? new Date(value) : new Date(today.getTime())
     newDate.setHours(h)
     onChange?.(newDate)
   }
 
   function setMinutes(m: number): void {
     if (m < 0 || m > 59) return
-    const newDate = value ? new Date(value) : new Date()
+    const newDate = value ? new Date(value) : new Date(today.getTime())
     newDate.setMinutes(m)
     onChange?.(newDate)
   }

package/dist/device-frame/device-frame.ts

@@ -1,5 +1,3 @@
-import type { AccessibilityProps } from '../shared/index.ts'
-
 export type DeviceType = 'iphone' | 'ipad' | 'android-phone' | 'android-tablet'
 export type DeviceOrientation = 'portrait' | 'landscape'
 
@@ -27,7 +25,7 @@ export interface DeviceFrameAPI {
   /** Computed dimensions for the device */
   dimensions: DeviceDimensions
   /** ARIA attributes for the device frame */
-  ariaProps: Partial<AccessibilityProps> & Record<string, unknown>
+  ariaProps: Record<string, string | number | boolean>
   /** Data attributes for styling hooks */
   dataAttributes: Record<string, string>
 }
@@ -92,7 +90,7 @@ export function createDeviceFrame(props: DeviceFrameProps): DeviceFrameAPI {
     homeIndicator: spec.homeIndicator,
   }
 
-  const ariaProps: Partial<AccessibilityProps> & Record<string, unknown> = {
+  const ariaProps: Record<string, string | number | boolean> = {
     role: 'img',
     'aria-label': `${DEVICE_LABELS[device]} device frame in ${orientation} orientation`,
   }

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

@@ -1,4 +1,3 @@
-import type { AccessibilityProps } from '../shared/index.ts'
 import { generateId } from '../shared/index.ts'
 import {
   EMOJI_DATA,
@@ -39,7 +38,7 @@ export interface EmojiPickerAPI {
   /** Category tabs with labels */
   categoryTabs: { category: EmojiCategory; label: string; emoji: string }[]
   /** ARIA props for the picker container */
-  ariaProps: Partial<AccessibilityProps> & Record<string, unknown>
+  ariaProps: Record<string, string | number | boolean>
   /** ARIA props for the search input */
   searchInputProps: Record<string, unknown>
   /** Get ARIA props for an emoji button */
@@ -118,7 +117,7 @@ export function createEmojiPicker(props: EmojiPickerProps = {}): EmojiPickerAPI
     emoji: CATEGORY_ICONS[cat],
   }))
 
-  const ariaProps: Partial<AccessibilityProps> & Record<string, unknown> = {
+  const ariaProps: Record<string, string | number | boolean> = {
     role: 'dialog',
     'aria-labelledby': labelId,
     id: containerId,

package/dist/footer/footer.ts

@@ -13,6 +13,8 @@ export interface FooterProps {
   copyright?: string
   socialLinks?: SocialLink[]
   columns?: FooterColumn[]
+  /** Year for the default copyrightText. Default: ambient current year — inject to avoid year-boundary SSR/CSR mismatch. */
+  year?: number
 }
 
 export interface FooterAPI {
@@ -22,7 +24,8 @@ export interface FooterAPI {
 
 export function createFooter(props: FooterProps = {}): FooterAPI {
   const { copyright } = props
-  const year = new Date().getFullYear()
+  // Injection boundary: ambient year is the default; inject `year` so SSR and client agree.
+  const year = props.year ?? new Date().getFullYear()
   const copyrightText = copyright ?? `© ${year} All rights reserved.`
 
   return {

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,

package/dist/slider/slider.ts

@@ -1,2 +1,134 @@
-// Core slider logic
-export interface SliderProps {}
+/**
+ * @refraction-ui/slider — headless slider.
+ *
+ * Owns the *behavior* of a single-value range slider: min/max clamping,
+ * step rounding, and keyboard increment/decrement semantics. It has NO UI
+ * opinion — adapters render the control (a native `<input type="range">` in
+ * React, which already applies these same keyboard rules natively) and spread
+ * the ARIA object.
+ */
+
+/** Options for {@link createSlider}. */
+export interface SliderProps {
+  /** Current value. Clamped into `[min, max]` and rounded to `step`. */
+  value?: number
+  /** Minimum selectable value (default 0). */
+  min?: number
+  /** Maximum selectable value (default 100). */
+  max?: number
+  /** Granularity between selectable values (default 1). */
+  step?: number
+  /** Disables the control. */
+  disabled?: boolean
+  /** Accessible label attached to the slider, when provided. */
+  'aria-label'?: string
+}
+
+/** The computed view of a slider control. */
+export interface SliderAPI {
+  /** Normalized value (clamped + step-rounded). */
+  value: number
+  min: number
+  max: number
+  step: number
+  /** Value position within the range, 0–100. */
+  percentage: number
+  /** ARIA attributes for the slider element (`role="slider"` + value attrs). */
+  ariaProps: Record<string, string | number | boolean>
+  /** Data attributes for styling hooks. */
+  dataAttributes: Record<string, string>
+}
+
+/** Clamp a value into `[min, max]`. */
+export function clampSliderValue(value: number, min = 0, max = 100): number {
+  if (Number.isNaN(value)) return min
+  return Math.min(Math.max(value, min), max)
+}
+
+/**
+ * Round a value to the nearest multiple of `step`, offset from `min`.
+ * Non-positive steps leave the value unchanged. The result is re-rounded to
+ * the step's decimal precision to avoid float noise (e.g. 0.30000000000000004).
+ */
+export function roundToStep(value: number, min = 0, step = 1): number {
+  if (!step || step <= 0 || Number.isNaN(value)) return value
+  const snapped = min + Math.round((value - min) / step) * step
+  const decimals = (String(step).split('.')[1] ?? '').length
+  return Number(snapped.toFixed(decimals))
+}
+
+/**
+ * Pure keyboard rule for a slider (WAI-ARIA slider pattern), shared by every
+ * adapter that does NOT render a native range input (native inputs already
+ * implement these keys):
+ *
+ * - ArrowRight / ArrowUp   → +step
+ * - ArrowLeft  / ArrowDown → -step
+ * - PageUp   / PageDown    → ±10×step
+ * - Home / End             → min / max
+ *
+ * The result is clamped; unhandled keys return `current` unchanged.
+ */
+export function getSliderValueFromKey(
+  current: number,
+  key: string,
+  options: { min?: number; max?: number; step?: number } = {},
+): number {
+  const { min = 0, max = 100, step = 1 } = options
+  switch (key) {
+    case 'ArrowRight':
+    case 'ArrowUp':
+      return clampSliderValue(current + step, min, max)
+    case 'ArrowLeft':
+    case 'ArrowDown':
+      return clampSliderValue(current - step, min, max)
+    case 'PageUp':
+      return clampSliderValue(current + step * 10, min, max)
+    case 'PageDown':
+      return clampSliderValue(current - step * 10, min, max)
+    case 'Home':
+      return min
+    case 'End':
+      return max
+    default:
+      return current
+  }
+}
+
+/**
+ * createSlider — the framework-agnostic view of a slider: normalized value,
+ * percentage position, and the ARIA object (`role="slider"`,
+ * `aria-valuemin/max/now`). Adapters own the value state
+ * (controlled/uncontrolled) and call this per render.
+ */
+export function createSlider(props: SliderProps = {}): SliderAPI {
+  const min = props.min ?? 0
+  const max = props.max ?? 100
+  const step = props.step ?? 1
+  const value = clampSliderValue(roundToStep(props.value ?? min, min, step), min, max)
+  const percentage = max === min ? 0 : ((value - min) / (max - min)) * 100
+
+  const ariaProps: Record<string, string | number | boolean> = {
+    role: 'slider',
+    'aria-valuemin': min,
+    'aria-valuemax': max,
+    'aria-valuenow': value,
+    'aria-orientation': 'horizontal',
+  }
+  if (props.disabled) ariaProps['aria-disabled'] = true
+  if (props['aria-label']) ariaProps['aria-label'] = props['aria-label']
+
+  return {
+    value,
+    min,
+    max,
+    step,
+    percentage,
+    ariaProps,
+    dataAttributes: {
+      'data-value': String(value),
+      'data-min': String(min),
+      'data-max': String(max),
+    },
+  }
+}

package/dist/status-indicator/status-indicator.ts

@@ -1,5 +1,3 @@
-import type { AccessibilityProps } from '../shared/index.ts'
-
 export type StatusType = 'success' | 'error' | 'warning' | 'info' | 'pending' | 'neutral'
 
 export interface StatusProps {
@@ -13,7 +11,7 @@ export interface StatusProps {
 
 export interface StatusAPI {
   /** ARIA attributes for the status indicator */
-  ariaProps: Partial<AccessibilityProps> & Record<string, unknown>
+  ariaProps: Record<string, string | number | boolean>
   /** The status type */
   type: StatusType
   /** The display label */
@@ -54,7 +52,7 @@ export function createStatusIndicator(props: StatusProps): StatusAPI {
   const label = labelOverride ?? STATUS_INDICATOR_LABELS[type]
   const pulse = pulseOverride ?? (type === 'pending')
 
-  const ariaProps: Partial<AccessibilityProps> & Record<string, unknown> = {
+  const ariaProps: Record<string, string | number | boolean> = {
     role: 'status',
     'aria-label': label,
   }

package/dist/thread-view/thread-view.ts

@@ -1,4 +1,3 @@
-import type { AccessibilityProps } from '../shared/index.ts'
 import { generateId } from '../shared/index.ts'
 
 export interface MessageReaction {
@@ -70,11 +69,11 @@ export interface ThreadViewAPI {
   /** Format relative time (e.g., "2 minutes ago") */
   formatRelativeTime(date: Date): string
   /** ARIA props for the thread container */
-  ariaProps: Partial<AccessibilityProps> & Record<string, unknown>
+  ariaProps: Record<string, string | number | boolean>
   /** Get ARIA props for a message */
-  getMessageAriaProps(message: MessageData): Record<string, unknown>
+  getMessageAriaProps(message: MessageData): Record<string, string | number | boolean>
   /** Get ARIA props for a reply button */
-  getReplyButtonAriaProps(messageId: string): Record<string, unknown>
+  getReplyButtonAriaProps(messageId: string): Record<string, string | number | boolean>
   /** Generated IDs */
   ids: {
     thread: string
@@ -132,14 +131,14 @@ export function createThreadView(props: ThreadViewProps): ThreadViewAPI {
     onReact?.(messageId, emoji)
   }
 
-  const ariaProps: Partial<AccessibilityProps> & Record<string, unknown> = {
+  const ariaProps: Record<string, string | number | boolean> = {
     role: 'log',
     'aria-label': 'Message thread',
     'aria-live': 'polite',
     id: threadId,
   }
 
-  function getMessageAriaProps(message: MessageData): Record<string, unknown> {
+  function getMessageAriaProps(message: MessageData): Record<string, string | number | boolean> {
     const isOwn = currentUserId && message.author.id === currentUserId
     return {
       role: 'article',
@@ -147,7 +146,7 @@ export function createThreadView(props: ThreadViewProps): ThreadViewAPI {
     }
   }
 
-  function getReplyButtonAriaProps(_messageId: string): Record<string, unknown> {
+  function getReplyButtonAriaProps(_messageId: string): Record<string, string | number | boolean> {
     return {
       role: 'button',
       'aria-label': `Reply to message`,

package/dist/toast/toast.ts

@@ -25,6 +25,8 @@ export interface ToastProps {
   open?: boolean
   /** Callback when open state changes */
   onOpenChange?: (open: boolean) => void
+  /** Elapsed-time clock for timer pause/resume math (ms). Default: ambient `Date.now()` — inject for deterministic tests. */
+  now?: () => number
 }
 
 export interface ToastState {
@@ -55,6 +57,8 @@ export function createToast(props: ToastProps = {}): ToastAPI {
     onOpenChange,
   } = props
 
+  // Injection boundary: ambient time is the default; inject `now` for deterministic timer math.
+  const now = props.now ?? (() => Date.now())
   let isOpen = controlledOpen ?? true
   let timerId: ReturnType<typeof setTimeout> | null = null
   let remaining = duration
@@ -77,21 +81,21 @@ export function createToast(props: ToastProps = {}): ToastAPI {
     if (duration <= 0) return
     clearTimer()
     remaining = duration
-    startedAt = Date.now()
+    startedAt = now()
     timerId = setTimeout(dismiss, remaining)
   }
 
   function pauseTimer(): void {
     if (timerId === null) return
     clearTimer()
-    remaining = remaining - (Date.now() - startedAt)
+    remaining = remaining - (now() - startedAt)
     if (remaining < 0) remaining = 0
   }
 
   function resumeTimer(): void {
     if (duration <= 0 || remaining <= 0) return
     clearTimer()
-    startedAt = Date.now()
+    startedAt = now()
     timerId = setTimeout(dismiss, remaining)
   }
 
@@ -136,7 +140,14 @@ export interface ToastManagerAPI {
   subscribe(fn: (toasts: ReadonlyArray<ToastEntry>) => void): () => void
 }
 
-export function createToastManager(): ToastManagerAPI {
+export interface ToastManagerConfig {
+  /** Clock for entry `createdAt` stamps (ms). Default: ambient `Date.now()` — inject for deterministic tests. */
+  now?: () => number
+}
+
+export function createToastManager(config: ToastManagerConfig = {}): ToastManagerAPI {
+  // Injection boundary: ambient time is the default; inject `now` for deterministic createdAt.
+  const now = config.now ?? (() => Date.now())
   let toasts: ToastEntry[] = []
   const listeners = new Set<(toasts: ReadonlyArray<ToastEntry>) => void>()
   const timers = new Map<string, ReturnType<typeof setTimeout>>()
@@ -171,7 +182,7 @@ export function createToastManager(): ToastManagerAPI {
       message,
       variant,
       duration,
-      createdAt: Date.now(),
+      createdAt: now(),
     }
 
     toasts = [...toasts, entry]

package/dist/voice-pill/voice-pill.ts

@@ -1,5 +1,3 @@
-import type { AccessibilityProps } from '../shared/index.ts'
-
 export type VoicePillSpeaker = 'ai' | 'user' | (string & {})
 
 export type VoicePillPosition =
@@ -60,7 +58,7 @@ export interface VoicePillAPI {
   /** Invoke the mute callback when provided */
   toggleMute(): void
   /** ARIA props for the live status pill */
-  ariaProps: Partial<AccessibilityProps> & Record<string, unknown>
+  ariaProps: Record<string, string | number | boolean>
   /** ARIA props for the mute toggle */
   toggleMuteAriaProps: Record<string, unknown>
   /** Data attributes reflecting speaker/state */
@@ -196,7 +194,7 @@ export function createVoicePill(props: VoicePillProps): VoicePillAPI {
     onToggleMute?.()
   }
 
-  const ariaProps: Partial<AccessibilityProps> & Record<string, unknown> = {
+  const ariaProps: Record<string, string | number | boolean> = {
     role: 'status',
     'aria-live': 'polite',
     'aria-atomic': true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@refraction-ui/astro",
-  "version": "0.17.1",
+  "version": "0.17.2",
   "description": "All Refraction UI Astro components in one package",
   "type": "module",
   "exports": {