@refraction-ui/astro 0.4.12 → 0.5.0

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

@@ -0,0 +1,234 @@
+import type { AccessibilityProps } from '../shared/index.ts'
+
+export type VoicePillSpeaker = 'ai' | 'user' | (string & {})
+
+export type VoicePillPosition =
+  | 'top-start'
+  | 'top-center'
+  | 'top-end'
+  | 'bottom-start'
+  | 'bottom-center'
+  | 'bottom-end'
+  | 'left-start'
+  | 'left-center'
+  | 'left-end'
+  | 'right-start'
+  | 'right-center'
+  | 'right-end'
+
+export interface VoicePillProps {
+  /** Speaker identity used for labels and data-speaker theming */
+  speaker?: VoicePillSpeaker
+  /** Primary voice status text */
+  label: string
+  /** Optional secondary status text */
+  sub?: string
+  /** Voice activity intensity, clamped from 0 to 1 */
+  intensity?: number
+  /** Whether voice output/input is muted */
+  muted?: boolean
+  /** Callback for the optional mute toggle */
+  onToggleMute?: () => void
+  /** Fixed viewport position */
+  position?: VoicePillPosition
+}
+
+export interface VoicePillStyleVars {
+  [key: `--${string}`]: string
+}
+
+export interface VoicePillAPI {
+  /** Display speaker label */
+  speaker: string
+  /** Normalized key for data-speaker */
+  speakerKey: string
+  /** Primary label */
+  label: string
+  /** Secondary label */
+  sub?: string
+  /** Clamped raw intensity */
+  intensity: number
+  /** Intensity used for visual animation after muted state is applied */
+  visualIntensity: number
+  /** Muted state */
+  muted: boolean
+  /** Fixed viewport position */
+  position: VoicePillPosition
+  /** Fallback initials for the speaker avatar */
+  initials: string
+  /** Invoke the mute callback when provided */
+  toggleMute(): void
+  /** ARIA props for the live status pill */
+  ariaProps: Partial<AccessibilityProps> & Record<string, unknown>
+  /** ARIA props for the mute toggle */
+  toggleMuteAriaProps: Record<string, unknown>
+  /** Data attributes reflecting speaker/state */
+  dataAttributes: Record<string, string>
+  /** CSS custom properties that drive pulse visuals */
+  style: VoicePillStyleVars
+}
+
+export const DEFAULT_VOICE_PILL_SPEAKER = 'ai'
+export const DEFAULT_VOICE_PILL_POSITION: VoicePillPosition = 'bottom-center'
+
+function formatNumber(value: number): string {
+  return Number(value.toFixed(3)).toString()
+}
+
+function getRawSpeaker(speaker?: VoicePillSpeaker): string {
+  const value = String(speaker ?? DEFAULT_VOICE_PILL_SPEAKER).trim()
+  return value.length > 0 ? value : DEFAULT_VOICE_PILL_SPEAKER
+}
+
+export function clampVoicePillIntensity(intensity = 0): number {
+  const value = Number(intensity)
+
+  if (!Number.isFinite(value)) {
+    return 0
+  }
+
+  return Math.min(1, Math.max(0, value))
+}
+
+export function getVoicePillSpeakerKey(speaker?: VoicePillSpeaker): string {
+  const normalized = getRawSpeaker(speaker)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+
+  return normalized.length > 0 ? normalized : DEFAULT_VOICE_PILL_SPEAKER
+}
+
+export function getVoicePillSpeakerLabel(speaker?: VoicePillSpeaker): string {
+  const raw = getRawSpeaker(speaker)
+  const key = getVoicePillSpeakerKey(raw)
+
+  if (key === 'ai') return 'AI'
+  if (key === 'user') return 'User'
+
+  return raw
+}
+
+export function getVoicePillInitials(speaker?: VoicePillSpeaker): string {
+  const key = getVoicePillSpeakerKey(speaker)
+
+  if (key === 'ai') return 'AI'
+  if (key === 'user') return 'U'
+
+  const initials = getVoicePillSpeakerLabel(speaker)
+    .split(/[\s_-]+/)
+    .map((part) => part.charAt(0))
+    .filter(Boolean)
+    .join('')
+    .slice(0, 2)
+    .toUpperCase()
+
+  return initials.length > 0 ? initials : 'V'
+}
+
+export function getVoicePillPosition(
+  position?: VoicePillPosition,
+): VoicePillPosition {
+  return position ?? DEFAULT_VOICE_PILL_POSITION
+}
+
+export function getVoicePillAriaLabel(props: {
+  speaker?: VoicePillSpeaker
+  label: string
+  sub?: string
+  muted?: boolean
+}): string {
+  const parts = [`${getVoicePillSpeakerLabel(props.speaker)}: ${props.label}`]
+
+  if (props.sub) {
+    parts.push(props.sub)
+  }
+
+  if (props.muted) {
+    parts.push('muted')
+  }
+
+  return parts.join(', ')
+}
+
+export function getVoicePillPulseStyle(
+  intensity?: number,
+  muted = false,
+): VoicePillStyleVars {
+  const clamped = clampVoicePillIntensity(intensity)
+  const visualIntensity = muted ? 0 : clamped
+  const ringOpacity = visualIntensity === 0 ? 0 : 0.12 + visualIntensity * 0.42
+  const ringScale = 1 + visualIntensity * 0.35
+  const duration = visualIntensity === 0
+    ? 1800
+    : Math.round(1700 - visualIntensity * 700)
+
+  return {
+    '--rfr-voice-pill-intensity': formatNumber(clamped),
+    '--rfr-voice-pill-visual-intensity': formatNumber(visualIntensity),
+    '--rfr-voice-pill-ring-opacity': formatNumber(ringOpacity),
+    '--rfr-voice-pill-ring-scale': formatNumber(ringScale),
+    '--rfr-voice-pill-pulse-duration': `${duration}ms`,
+    '--rfr-voice-pill-pulse-delay': `-${Math.round(duration / 2)}ms`,
+  }
+}
+
+export function createVoicePill(props: VoicePillProps): VoicePillAPI {
+  const {
+    speaker: speakerProp,
+    label,
+    sub,
+    intensity: intensityProp,
+    muted: mutedProp = false,
+    onToggleMute,
+    position: positionProp,
+  } = props
+
+  const speaker = getVoicePillSpeakerLabel(speakerProp)
+  const speakerKey = getVoicePillSpeakerKey(speakerProp)
+  const intensity = clampVoicePillIntensity(intensityProp)
+  const muted = Boolean(mutedProp)
+  const visualIntensity = muted ? 0 : intensity
+  const position = getVoicePillPosition(positionProp)
+
+  function toggleMute(): void {
+    onToggleMute?.()
+  }
+
+  const ariaProps: Partial<AccessibilityProps> & Record<string, unknown> = {
+    role: 'status',
+    'aria-live': 'polite',
+    'aria-atomic': true,
+    'aria-label': getVoicePillAriaLabel({ speaker: speakerProp, label, sub, muted }),
+  }
+
+  const toggleMuteAriaProps: Record<string, unknown> = {
+    'aria-label': muted ? 'Unmute voice' : 'Mute voice',
+    'aria-pressed': muted,
+  }
+
+  const dataAttributes: Record<string, string> = {
+    'data-speaker': speakerKey,
+    'data-muted': String(muted),
+    'data-position': position,
+    'data-intensity': formatNumber(intensity),
+    'data-active': String(visualIntensity > 0),
+  }
+
+  return {
+    speaker,
+    speakerKey,
+    label,
+    sub,
+    intensity,
+    visualIntensity,
+    muted,
+    position,
+    initials: getVoicePillInitials(speakerProp),
+    toggleMute,
+    ariaProps,
+    toggleMuteAriaProps,
+    dataAttributes,
+    style: getVoicePillPulseStyle(intensity, muted),
+  }
+}

package/dist/waveform/index.ts

@@ -0,0 +1,39 @@
+export {
+  DEFAULT_WAVEFORM_BAR_COUNT,
+  DEFAULT_WAVEFORM_COLOR,
+  DEFAULT_WAVEFORM_HEIGHT,
+  DEFAULT_WAVEFORM_INTENSITY,
+  DEFAULT_WAVEFORM_SMOOTHING,
+  createSilentSamples,
+  createIntensitySamples,
+  createWaveform,
+  getWaveformPeak,
+  isWaveformSampleInput,
+  normalizeBarCount,
+  normalizeIntensity,
+  normalizeSmoothing,
+  normalizeWaveformConfig,
+  normalizeWaveformSamples,
+  resampleWaveformSamples,
+  scaleWaveformSamples,
+  smoothWaveformSamples,
+  toCssDimension,
+  type NormalizedWaveformConfig,
+  type WaveformAPI,
+  type WaveformProps,
+  type WaveformSampleInput,
+  type WaveformSource,
+  type WaveformVariant,
+} from './waveform.js'
+
+export {
+  drawWaveform,
+  prepareWaveformCanvas,
+  type WaveformCanvasSize,
+  type WaveformRenderOptions,
+} from './waveform-renderer.js'
+
+export {
+  waveformCanvasVariants,
+  waveformVariants,
+} from './waveform.styles.js'

package/dist/waveform/waveform-renderer.ts

@@ -0,0 +1,174 @@
+import {
+  DEFAULT_WAVEFORM_COLOR,
+  DEFAULT_WAVEFORM_INTENSITY,
+  getWaveformPeak,
+  normalizeBarCount,
+  normalizeIntensity,
+  resampleWaveformSamples,
+  scaleWaveformSamples,
+  type WaveformSampleInput,
+  type WaveformVariant,
+} from './waveform.js'
+
+export interface WaveformCanvasSize {
+  width: number
+  height: number
+  pixelRatio?: number
+}
+
+export interface WaveformRenderOptions {
+  variant?: WaveformVariant
+  color?: string
+  intensity?: number
+  barCount?: number
+}
+
+export function prepareWaveformCanvas(
+  canvas: HTMLCanvasElement,
+  size: WaveformCanvasSize,
+): CanvasRenderingContext2D | null {
+  const width = Math.max(1, Math.floor(size.width))
+  const height = Math.max(1, Math.floor(size.height))
+  const pixelRatio = Math.max(1, size.pixelRatio ?? 1)
+  const pixelWidth = Math.floor(width * pixelRatio)
+  const pixelHeight = Math.floor(height * pixelRatio)
+
+  if (canvas.width !== pixelWidth) {
+    canvas.width = pixelWidth
+  }
+
+  if (canvas.height !== pixelHeight) {
+    canvas.height = pixelHeight
+  }
+
+  const context = canvas.getContext('2d')
+  if (!context) return null
+
+  context.setTransform(pixelRatio, 0, 0, pixelRatio, 0, 0)
+
+  return context
+}
+
+export function drawWaveform(
+  context: CanvasRenderingContext2D,
+  samples: WaveformSampleInput,
+  size: WaveformCanvasSize,
+  options: WaveformRenderOptions = {},
+): void {
+  const width = Math.max(1, Math.floor(size.width))
+  const height = Math.max(1, Math.floor(size.height))
+  const variant = options.variant ?? 'bars'
+  const color = options.color ?? DEFAULT_WAVEFORM_COLOR
+  const intensity = normalizeIntensity(options.intensity ?? DEFAULT_WAVEFORM_INTENSITY)
+  const barCount = normalizeBarCount(options.barCount)
+
+  context.clearRect(0, 0, width, height)
+  applyCanvasColor(context, color)
+
+  if (variant === 'line') {
+    drawLine(context, samples, width, height, intensity)
+    return
+  }
+
+  if (variant === 'rings') {
+    drawRings(context, samples, width, height, intensity)
+    return
+  }
+
+  drawBars(context, samples, width, height, intensity, barCount)
+}
+
+function drawBars(
+  context: CanvasRenderingContext2D,
+  samples: WaveformSampleInput,
+  width: number,
+  height: number,
+  intensity: number,
+  barCount: number,
+) {
+  const bars = scaleWaveformSamples(resampleWaveformSamples(samples, barCount), intensity)
+  const slotWidth = width / bars.length
+  const barWidth = Math.max(1, slotWidth * 0.64)
+  const center = height / 2
+
+  for (let i = 0; i < bars.length; i += 1) {
+    const value = Math.abs(bars[i])
+    const barHeight = Math.max(value * height, value > 0 ? 1 : 0)
+    const x = i * slotWidth + (slotWidth - barWidth) / 2
+    const y = center - barHeight / 2
+
+    context.fillRect(x, y, barWidth, barHeight)
+  }
+}
+
+function drawLine(
+  context: CanvasRenderingContext2D,
+  samples: WaveformSampleInput,
+  width: number,
+  height: number,
+  intensity: number,
+) {
+  const lineSamples = scaleWaveformSamples(samples, intensity)
+  const center = height / 2
+  const amplitude = height * 0.45
+
+  context.beginPath()
+
+  for (let i = 0; i < lineSamples.length; i += 1) {
+    const x = lineSamples.length <= 1 ? width / 2 : (i / (lineSamples.length - 1)) * width
+    const y = center - Number(lineSamples[i]) * amplitude
+
+    if (i === 0) {
+      context.moveTo(x, y)
+    } else {
+      context.lineTo(x, y)
+    }
+  }
+
+  context.lineWidth = Math.max(1.5, Math.min(width, height) * 0.025)
+  context.lineCap = 'round'
+  context.lineJoin = 'round'
+  context.stroke()
+}
+
+function drawRings(
+  context: CanvasRenderingContext2D,
+  samples: WaveformSampleInput,
+  width: number,
+  height: number,
+  intensity: number,
+) {
+  const peak = getWaveformPeak(scaleWaveformSamples(samples, intensity))
+  const minDimension = Math.min(width, height)
+  const centerX = width / 2
+  const centerY = height / 2
+  const ringCount = 3
+  const baseRadius = minDimension * 0.16
+  const radiusStep = minDimension * 0.13
+
+  context.save()
+  context.lineWidth = Math.max(1.5, minDimension * 0.018)
+
+  for (let i = 0; i < ringCount; i += 1) {
+    const progress = (i + 1) / ringCount
+    const pulse = peak * minDimension * 0.1 * progress
+    const radius = baseRadius + radiusStep * i + pulse
+
+    context.globalAlpha = 0.28 + progress * 0.34
+    context.beginPath()
+    context.arc(centerX, centerY, radius, 0, Math.PI * 2)
+    context.stroke()
+  }
+
+  context.restore()
+}
+
+function applyCanvasColor(context: CanvasRenderingContext2D, color: string) {
+  try {
+    context.fillStyle = color
+    context.strokeStyle = color
+  } catch {
+    context.fillStyle = '#000'
+    context.strokeStyle = '#000'
+  }
+}

package/dist/waveform/waveform.styles.ts

@@ -0,0 +1,19 @@
+import { cva } from '../shared/index.ts'
+
+export const waveformVariants = cva({
+  base: 'relative block overflow-hidden',
+  variants: {
+    variant: {
+      bars: '',
+      line: '',
+      rings: '',
+    },
+  },
+  defaultVariants: {
+    variant: 'bars',
+  },
+})
+
+export const waveformCanvasVariants = cva({
+  base: 'block h-full w-full',
+})

package/dist/waveform/waveform.ts

@@ -0,0 +1,249 @@
+import type { AccessibilityProps } from '../shared/index.ts'
+
+export type WaveformVariant = 'bars' | 'line' | 'rings'
+export type WaveformSampleInput = Float32Array | number[]
+export type WaveformSource = AnalyserNode | MediaStream | WaveformSampleInput
+
+export interface WaveformProps {
+  source?: WaveformSource
+  samples?: WaveformSampleInput
+  intensity?: number
+  variant?: WaveformVariant
+  height?: number | string
+  width?: number | string
+  barCount?: number
+  smoothing?: number
+  color?: string
+  paused?: boolean
+}
+
+export interface NormalizedWaveformConfig {
+  variant: WaveformVariant
+  intensity: number
+  height: number | string
+  width: number | string
+  barCount: number
+  smoothing: number
+  color: string
+  paused: boolean
+}
+
+export interface WaveformAPI {
+  config: NormalizedWaveformConfig
+  samples: Float32Array
+  ariaProps: Partial<AccessibilityProps>
+  dataAttributes: Record<'data-variant' | 'data-paused', string>
+  getSamples: (barCount?: number) => Float32Array
+}
+
+export const DEFAULT_WAVEFORM_BAR_COUNT = 48
+export const DEFAULT_WAVEFORM_COLOR = 'var(--accent-2)'
+export const DEFAULT_WAVEFORM_HEIGHT = 80
+export const DEFAULT_WAVEFORM_INTENSITY = 1
+export const DEFAULT_WAVEFORM_SMOOTHING = 0.8
+
+const MAX_BAR_COUNT = 1024
+const MAX_INTENSITY = 1
+
+export function normalizeBarCount(value: number | undefined): number {
+  if (value == null || !Number.isFinite(value)) return DEFAULT_WAVEFORM_BAR_COUNT
+
+  return Math.min(MAX_BAR_COUNT, Math.max(1, Math.round(value)))
+}
+
+export function normalizeSmoothing(value: number | undefined): number {
+  if (value == null || !Number.isFinite(value)) return DEFAULT_WAVEFORM_SMOOTHING
+
+  return Math.min(0.99, Math.max(0, value))
+}
+
+export function normalizeIntensity(value: number | undefined): number {
+  if (value == null || !Number.isFinite(value)) return DEFAULT_WAVEFORM_INTENSITY
+
+  return Math.min(MAX_INTENSITY, Math.max(0, value))
+}
+
+export function normalizeWaveformConfig(props: WaveformProps = {}): NormalizedWaveformConfig {
+  return {
+    variant: props.variant ?? 'bars',
+    intensity: normalizeIntensity(props.intensity),
+    height: props.height ?? DEFAULT_WAVEFORM_HEIGHT,
+    width: props.width ?? '100%',
+    barCount: normalizeBarCount(props.barCount),
+    smoothing: normalizeSmoothing(props.smoothing),
+    color: props.color ?? DEFAULT_WAVEFORM_COLOR,
+    paused: props.paused ?? false,
+  }
+}
+
+export function isWaveformSampleInput(value: unknown): value is WaveformSampleInput {
+  return value instanceof Float32Array || Array.isArray(value)
+}
+
+export function createSilentSamples(count = DEFAULT_WAVEFORM_BAR_COUNT): Float32Array {
+  return new Float32Array(normalizeBarCount(count))
+}
+
+export function createIntensitySamples(
+  intensity = DEFAULT_WAVEFORM_INTENSITY,
+  count = DEFAULT_WAVEFORM_BAR_COUNT,
+): Float32Array {
+  const normalizedIntensity = normalizeIntensity(intensity)
+  const normalizedCount = normalizeBarCount(count)
+  const samples = new Float32Array(normalizedCount)
+
+  if (normalizedIntensity === 0) return samples
+
+  for (let i = 0; i < normalizedCount; i += 1) {
+    const progress = normalizedCount <= 1 ? 0.5 : i / (normalizedCount - 1)
+    const envelope = 0.35 + Math.sin(progress * Math.PI) * 0.65
+    const carrier = Math.sin(progress * Math.PI * 6)
+    samples[i] = carrier * envelope * normalizedIntensity
+  }
+
+  return samples
+}
+
+export function normalizeWaveformSamples(
+  input: WaveformSampleInput | undefined,
+  targetCount?: number,
+): Float32Array {
+  const sourceLength = input?.length ?? 0
+
+  if (sourceLength === 0) {
+    return targetCount == null ? new Float32Array() : createSilentSamples(targetCount)
+  }
+
+  const normalized = new Float32Array(sourceLength)
+  let maxAbs = 0
+
+  for (let i = 0; i < sourceLength; i += 1) {
+    const value = Number(input?.[i])
+    const sample = Number.isFinite(value) ? value : 0
+    normalized[i] = sample
+    maxAbs = Math.max(maxAbs, Math.abs(sample))
+  }
+
+  const divisor = maxAbs > 1 ? maxAbs : 1
+
+  for (let i = 0; i < normalized.length; i += 1) {
+    normalized[i] = clamp(normalized[i] / divisor, -1, 1)
+  }
+
+  if (targetCount == null || targetCount === normalized.length) {
+    return normalized
+  }
+
+  return resampleWaveformSamples(normalized, targetCount)
+}
+
+export function resampleWaveformSamples(
+  samples: WaveformSampleInput,
+  targetCount: number,
+): Float32Array {
+  const count = normalizeBarCount(targetCount)
+  const sourceLength = samples.length
+
+  if (sourceLength === 0) return createSilentSamples(count)
+  if (sourceLength === count) return Float32Array.from(samples)
+
+  const output = new Float32Array(count)
+
+  for (let i = 0; i < count; i += 1) {
+    const start = (i * sourceLength) / count
+    const end = ((i + 1) * sourceLength) / count
+    const firstIndex = Math.floor(start)
+    const lastIndex = Math.max(firstIndex + 1, Math.ceil(end))
+    let total = 0
+    let values = 0
+
+    for (let j = firstIndex; j < lastIndex && j < sourceLength; j += 1) {
+      total += Number(samples[j])
+      values += 1
+    }
+
+    output[i] = values > 0 ? total / values : Number(samples[Math.min(firstIndex, sourceLength - 1)])
+  }
+
+  return output
+}
+
+export function smoothWaveformSamples(
+  previous: WaveformSampleInput | undefined,
+  next: WaveformSampleInput,
+  smoothing = DEFAULT_WAVEFORM_SMOOTHING,
+): Float32Array {
+  if (previous == null || previous.length === 0) {
+    return Float32Array.from(next)
+  }
+
+  const amount = normalizeSmoothing(smoothing)
+  const output = new Float32Array(next.length)
+
+  for (let i = 0; i < next.length; i += 1) {
+    const previousValue = Number(previous[i] ?? next[i])
+    output[i] = previousValue * amount + Number(next[i]) * (1 - amount)
+  }
+
+  return output
+}
+
+export function scaleWaveformSamples(
+  samples: WaveformSampleInput,
+  intensity = DEFAULT_WAVEFORM_INTENSITY,
+): Float32Array {
+  const amount = normalizeIntensity(intensity)
+  const output = new Float32Array(samples.length)
+
+  for (let i = 0; i < samples.length; i += 1) {
+    output[i] = clamp(Number(samples[i]) * amount, -1, 1)
+  }
+
+  return output
+}
+
+export function getWaveformPeak(samples: WaveformSampleInput): number {
+  let peak = 0
+
+  for (let i = 0; i < samples.length; i += 1) {
+    peak = Math.max(peak, Math.abs(Number(samples[i]) || 0))
+  }
+
+  return Math.min(1, peak)
+}
+
+export function toCssDimension(value: number | string | undefined): string | undefined {
+  if (value == null) return undefined
+
+  return typeof value === 'number' ? `${value}px` : value
+}
+
+export function createWaveform(props: WaveformProps = {}): WaveformAPI {
+  const config = normalizeWaveformConfig(props)
+  const inputSamples = props.samples ?? (isWaveformSampleInput(props.source) ? props.source : undefined)
+  const samples = inputSamples == null
+    ? createIntensitySamples(config.intensity, config.barCount)
+    : normalizeWaveformSamples(inputSamples, config.barCount)
+
+  return {
+    config,
+    samples,
+    ariaProps: {
+      role: 'img',
+      'aria-label': 'Audio waveform',
+    },
+    dataAttributes: {
+      'data-variant': config.variant,
+      'data-paused': String(config.paused),
+    },
+    getSamples(barCount = config.barCount) {
+      return inputSamples == null
+        ? createIntensitySamples(config.intensity, barCount)
+        : normalizeWaveformSamples(inputSamples, barCount)
+    },
+  }
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, value))
+}