@refraction-ui/astro 0.11.1 → 0.13.0

package/dist/live-captions/live-captions.ts

@@ -0,0 +1,57 @@
+/** A single caption cue — may be interim (non-final) while speech is in flight. */
+export interface CaptionCue {
+  /** Unique identifier for this cue. */
+  id: string
+  /** Speaker name, shown as a prefix when present. */
+  speaker?: string
+  /** The caption text. */
+  text: string
+  /** Whether this cue is finalised (true) or still being transcribed (false/absent). */
+  final?: boolean
+}
+
+/**
+ * Return the last `maxLines` cues to display in the caption overlay.
+ * Preserves ordering (oldest first within the slice) so the overlay reads top-to-bottom.
+ */
+export function visibleCues(cues: CaptionCue[], maxLines = 2): CaptionCue[] {
+  if (maxLines <= 0) return []
+  return cues.slice(-maxLines)
+}
+
+/**
+ * Format a single cue for display.
+ * When `speaker` is present the result is `'Maya: the bottleneck is review capacity'`.
+ * Without a speaker it is just the text.
+ */
+export function formatCue(cue: CaptionCue): string {
+  return cue.speaker ? `${cue.speaker}: ${cue.text}` : cue.text
+}
+
+export interface LiveCaptionsAPI {
+  /** ARIA attributes to spread on the caption container element. */
+  ariaProps: Record<string, string | number | boolean>
+  /** Data attributes for styling hooks. */
+  dataAttributes: Record<string, string>
+}
+
+/**
+ * Build the framework-agnostic accessibility props for a live-caption overlay.
+ *
+ * Returns `role="log"` with `aria-live="polite"` and `aria-atomic=false` so
+ * screen readers announce individual cues as they arrive without re-reading the
+ * whole log. Adapters spread these onto the container element.
+ */
+export function createLiveCaptions(): LiveCaptionsAPI {
+  const ariaProps: Record<string, string | number | boolean> = {
+    role: 'log',
+    'aria-live': 'polite',
+    'aria-atomic': false,
+  }
+
+  const dataAttributes: Record<string, string> = {
+    'data-component': 'live-captions',
+  }
+
+  return { ariaProps, dataAttributes }
+}

package/dist/live-cursors/index.ts

@@ -0,0 +1,14 @@
+export {
+  createLiveCursors,
+  assignCursorColor,
+  CURSOR_COLORS,
+  type CursorData,
+  type LiveCursorsAPI,
+} from './live-cursors.js'
+
+export {
+  liveCursorsVariants,
+  cursorWrapperClass,
+  cursorArrowClass,
+  cursorLabelClass,
+} from './live-cursors.styles.js'

package/dist/live-cursors/live-cursors.styles.ts

@@ -0,0 +1,41 @@
+import { cva } from '../shared/index.ts'
+
+/**
+ * Full-bleed overlay that contains all cursor elements.
+ * `pointer-events-none` and `overflow-hidden` ensure cursors are decorative
+ * and don't interfere with the underlying canvas interactions.
+ */
+export const liveCursorsVariants = cva({
+  base: 'absolute inset-0 overflow-hidden pointer-events-none',
+  variants: {
+    /** Future variant hook — reserved for theming overrides. */
+    hidden: {
+      true: 'invisible',
+      false: '',
+    },
+  },
+  defaultVariants: {
+    hidden: 'false',
+  },
+})
+
+/**
+ * Wrapper for a single cursor (SVG + label). Absolutely positioned via inline
+ * `left`/`top` style; the transition provides smooth movement when coordinates
+ * update.
+ */
+export const cursorWrapperClass =
+  'absolute flex flex-col items-start transition-[left,top] duration-100 ease-linear'
+
+/**
+ * The SVG cursor arrow container. Fill is applied via inline style (per
+ * collaborator color) so no utility class is needed here.
+ */
+export const cursorArrowClass = 'h-5 w-5 drop-shadow-sm'
+
+/**
+ * Name-label chip that appears below the cursor arrow. Background is applied
+ * via inline style (per collaborator color); text is always white for contrast.
+ */
+export const cursorLabelClass =
+  'mt-0.5 ml-2 rounded px-1.5 py-0.5 text-xs font-medium text-white shadow-sm whitespace-nowrap'

package/dist/live-cursors/live-cursors.ts

@@ -0,0 +1,73 @@
+/** Data for a single collaborator cursor. */
+export type CursorData = {
+  id: string
+  name: string
+  x: number
+  y: number
+  color?: string
+}
+
+/**
+ * A fixed palette of 8 hex colors for distinguishing collaborator cursors.
+ * Each color is vivid enough to be visible against both light and dark surfaces.
+ */
+export const CURSOR_COLORS: string[] = [
+  '#E94560', // red
+  '#F57C00', // orange
+  '#F9C840', // yellow
+  '#4CAF50', // green
+  '#00ACC1', // cyan
+  '#5C6BC0', // indigo
+  '#AB47BC', // purple
+  '#EC407A', // pink
+]
+
+/**
+ * Assign a stable color to a cursor.
+ *
+ * When `index` is supplied the color is simply `CURSOR_COLORS[index % length]`
+ * (deterministic for ordered participant lists). Otherwise a lightweight
+ * djb2-style hash of the `id` string is used so the same id always maps to the
+ * same color across renders without using Math.random or Date.now.
+ */
+export function assignCursorColor(id: string, index?: number): string {
+  if (index !== undefined) {
+    return CURSOR_COLORS[index % CURSOR_COLORS.length]
+  }
+
+  // djb2 hash — deterministic, no side-effects
+  let hash = 5381
+  for (let i = 0; i < id.length; i++) {
+    hash = ((hash << 5) + hash) ^ id.charCodeAt(i)
+    hash = hash >>> 0 // keep unsigned 32-bit
+  }
+  return CURSOR_COLORS[hash % CURSOR_COLORS.length]
+}
+
+export interface LiveCursorsAPI {
+  /** ARIA attributes to spread on the overlay container. */
+  ariaProps: Record<string, string | number | boolean>
+  /** Data attributes for styling hooks. */
+  dataAttributes: Record<string, string>
+}
+
+/**
+ * Build the framework-agnostic props for the live-cursors overlay.
+ *
+ * Cursors are purely decorative real-time presence indicators — aria-hidden
+ * true keeps them out of the accessibility tree. The group role is present for
+ * semantic correctness should a developer choose to un-hide it.
+ */
+export function createLiveCursors(): LiveCursorsAPI {
+  const ariaProps: Record<string, string | number | boolean> = {
+    role: 'group',
+    'aria-label': 'Collaborators',
+    'aria-hidden': true,
+  }
+
+  const dataAttributes: Record<string, string> = {
+    'data-live-cursors': '',
+  }
+
+  return { ariaProps, dataAttributes }
+}

package/dist/live-transcript/index.ts

@@ -0,0 +1,16 @@
+export {
+  groupConsecutiveBySpeaker,
+  createLiveTranscript,
+  type TranscriptEntry,
+  type TranscriptBlock,
+  type LiveTranscriptAPI,
+} from './live-transcript.js'
+
+export {
+  liveTranscriptVariants,
+  transcriptBlockVariants,
+  transcriptSpeakerRowClass,
+  transcriptSpeakerNameClass,
+  transcriptTimestampClass,
+  transcriptTextLineClass,
+} from './live-transcript.styles.js'

package/dist/live-transcript/live-transcript.styles.ts

@@ -0,0 +1,48 @@
+import { cva } from '../shared/index.ts'
+
+/**
+ * Scroll container that wraps all speaker blocks.
+ * The `compact` variant tightens the gap between blocks.
+ */
+export const liveTranscriptVariants = cva({
+  base: 'flex flex-col overflow-y-auto p-4 gap-4',
+  variants: {
+    compact: {
+      true: 'gap-2 p-3',
+      false: '',
+    },
+  },
+  defaultVariants: {
+    compact: 'false',
+  },
+})
+
+/** A single grouped speaker block (header + text lines). */
+export const transcriptBlockVariants = cva({
+  base: 'flex flex-col gap-1',
+  variants: {
+    compact: {
+      true: 'gap-0.5',
+      false: '',
+    },
+  },
+  defaultVariants: {
+    compact: 'false',
+  },
+})
+
+/** The row containing the speaker name and optional timestamp. */
+export const transcriptSpeakerRowClass =
+  'flex items-baseline gap-2'
+
+/** Speaker name badge / label. */
+export const transcriptSpeakerNameClass =
+  'text-sm font-semibold text-foreground leading-snug'
+
+/** Timestamp displayed beside the speaker name. */
+export const transcriptTimestampClass =
+  'text-xs text-muted-foreground tabular-nums'
+
+/** A single line of transcript text. */
+export const transcriptTextLineClass =
+  'text-sm text-foreground/80 leading-relaxed'

package/dist/live-transcript/live-transcript.ts

@@ -0,0 +1,82 @@
+/** A single transcript entry from one speaker at a point in time. */
+export interface TranscriptEntry {
+  /** Unique identifier for this entry. */
+  id: string
+  /** Display name of the speaker. */
+  speaker: string
+  /** The spoken text. */
+  text: string
+  /** Optional formatted timestamp string (e.g. "0:42"). */
+  timestamp?: string
+  /** Optional CSS color for the speaker's name (e.g. "#3b82f6"). */
+  speakerColor?: string
+}
+
+/** A merged block of consecutive entries from the same speaker. */
+export interface TranscriptBlock {
+  /** Speaker display name. */
+  speaker: string
+  /** Timestamp of the first entry in the run (if present). */
+  timestamp?: string
+  /** Optional CSS color for the speaker name. */
+  speakerColor?: string
+  /** All text segments from the consecutive run, in order. */
+  texts: string[]
+}
+
+/**
+ * Merge consecutive `TranscriptEntry` items from the same speaker into
+ * `TranscriptBlock` objects. A new block is started whenever the speaker
+ * changes; the block uses the timestamp of the *first* entry in that run.
+ */
+export function groupConsecutiveBySpeaker(
+  entries: TranscriptEntry[],
+): TranscriptBlock[] {
+  const blocks: TranscriptBlock[] = []
+
+  for (const entry of entries) {
+    const last = blocks[blocks.length - 1]
+    if (last && last.speaker === entry.speaker) {
+      last.texts.push(entry.text)
+    } else {
+      blocks.push({
+        speaker: entry.speaker,
+        timestamp: entry.timestamp,
+        speakerColor: entry.speakerColor,
+        texts: [entry.text],
+      })
+    }
+  }
+
+  return blocks
+}
+
+export interface LiveTranscriptAPI {
+  /**
+   * ARIA attributes to spread on the scroll container.
+   * Typed as a plain record so frameworks can spread without fighting their
+   * aria-* type narrowing.
+   */
+  ariaProps: Record<string, string | number | boolean>
+  /** Data attributes for styling hooks. */
+  dataAttributes: Record<string, string>
+}
+
+/**
+ * Build the framework-agnostic container props for a live transcript panel.
+ *
+ * Returns `role="log"` and `aria-live="polite"` so screen readers announce
+ * new transcript entries without interrupting the user.
+ */
+export function createLiveTranscript(): LiveTranscriptAPI {
+  const ariaProps: Record<string, string | number | boolean> = {
+    role: 'log',
+    'aria-live': 'polite',
+  }
+
+  const dataAttributes: Record<string, string> = {
+    'data-component': 'live-transcript',
+  }
+
+  return { ariaProps, dataAttributes }
+}

package/dist/mini-map/index.ts

@@ -0,0 +1,16 @@
+export {
+  contentBounds,
+  miniScale,
+  worldToMini,
+  viewportRectInMini,
+  createMiniMap,
+  type Rect,
+  type MiniMapItem,
+  type MiniMapAPI,
+} from './mini-map.js'
+
+export {
+  miniMapVariants,
+  miniMapDotClass,
+  miniMapViewportClass,
+} from './mini-map.styles.js'

package/dist/mini-map/mini-map.styles.ts

@@ -0,0 +1,32 @@
+import { cva } from '../shared/index.ts'
+
+/**
+ * The outer minimap box: small, rounded, bordered, card background.
+ * The `interactive` variant switches to grab cursor for clickable minimaps.
+ */
+export const miniMapVariants = cva({
+  base: [
+    'relative overflow-hidden rounded-md border border-border bg-card',
+    'select-none',
+  ].join(' '),
+  variants: {
+    interactive: {
+      true: 'cursor-grab active:cursor-grabbing',
+      false: '',
+    },
+  },
+  defaultVariants: {
+    interactive: 'false',
+  },
+})
+
+/** A single node dot in the minimap (represents one `MiniMapItem`). */
+export const miniMapDotClass =
+  'absolute rounded-sm bg-muted'
+
+/**
+ * The draggable viewport indicator rectangle.
+ * Uses a semi-transparent primary fill with a primary ring/border.
+ */
+export const miniMapViewportClass =
+  'absolute rounded-sm border border-primary ring-1 ring-primary bg-primary/10'

package/dist/mini-map/mini-map.ts

@@ -0,0 +1,122 @@
+/** A rectangle in 2-D space. */
+export interface Rect {
+  x: number
+  y: number
+  width: number
+  height: number
+}
+
+/** A single item to be represented as a dot on the minimap. */
+export interface MiniMapItem {
+  id: string
+  x: number
+  y: number
+  width?: number
+  height?: number
+}
+
+export interface MiniMapAPI {
+  /** ARIA attributes to spread on the minimap container element. */
+  ariaProps: { role: 'img'; 'aria-label': string }
+  /** Data attributes for styling hooks. */
+  dataAttributes: Record<string, string>
+}
+
+/**
+ * Compute the bounding box that encloses all items (using their x/y + optional
+ * width/height). Returns a zero-size rect at the origin when `items` is empty.
+ */
+export function contentBounds(items: MiniMapItem[]): Rect {
+  if (items.length === 0) return { x: 0, y: 0, width: 0, height: 0 }
+
+  let minX = Infinity
+  let minY = Infinity
+  let maxX = -Infinity
+  let maxY = -Infinity
+
+  for (const item of items) {
+    const right = item.x + (item.width ?? 0)
+    const bottom = item.y + (item.height ?? 0)
+    if (item.x < minX) minX = item.x
+    if (item.y < minY) minY = item.y
+    if (right > maxX) maxX = right
+    if (bottom > maxY) maxY = bottom
+  }
+
+  return { x: minX, y: minY, width: maxX - minX, height: maxY - minY }
+}
+
+/**
+ * Compute the uniform scale factor that fits `contentRect` into the minimap
+ * box (after subtracting `padding` on each side). Returns 1 when the content
+ * has zero area (nothing to scale).
+ */
+export function miniScale(
+  contentRect: Rect,
+  miniW: number,
+  miniH: number,
+  padding = 8,
+): number {
+  const availW = miniW - padding * 2
+  const availH = miniH - padding * 2
+  if (availW <= 0 || availH <= 0) return 1
+  if (contentRect.width === 0 || contentRect.height === 0) return 1
+  return Math.min(availW / contentRect.width, availH / contentRect.height)
+}
+
+/**
+ * Map a world-space point `{ x, y }` to minimap pixel coordinates.
+ *
+ * @param point       World coordinate
+ * @param contentRect Bounding box of all content (from `contentBounds`)
+ * @param scale       Scale factor (from `miniScale`)
+ * @param padding     Padding inset in px (must match the value passed to `miniScale`)
+ */
+export function worldToMini(
+  point: { x: number; y: number },
+  contentRect: Rect,
+  scale: number,
+  padding = 8,
+): { x: number; y: number } {
+  return {
+    x: (point.x - contentRect.x) * scale + padding,
+    y: (point.y - contentRect.y) * scale + padding,
+  }
+}
+
+/**
+ * Compute the position and size of the viewport indicator rectangle in
+ * minimap coordinates, ready to be applied as CSS `left/top/width/height`.
+ */
+export function viewportRectInMini(
+  viewport: Rect,
+  contentRect: Rect,
+  scale: number,
+  padding = 8,
+): Rect {
+  const { x, y } = worldToMini(
+    { x: viewport.x, y: viewport.y },
+    contentRect,
+    scale,
+    padding,
+  )
+  return {
+    x,
+    y,
+    width: viewport.width * scale,
+    height: viewport.height * scale,
+  }
+}
+
+/**
+ * Build the framework-agnostic ARIA props for the minimap container.
+ *
+ * Every adapter spreads `ariaProps` onto its outermost element; `dataAttributes`
+ * are available for CSS hooks.
+ */
+export function createMiniMap(): MiniMapAPI {
+  return {
+    ariaProps: { role: 'img', 'aria-label': 'Minimap' },
+    dataAttributes: { 'data-component': 'mini-map' },
+  }
+}

package/dist/password-input/index.ts

@@ -0,0 +1,9 @@
+export {
+  createPasswordInput,
+  DEFAULT_REVEAL_LABEL,
+  DEFAULT_HIDE_LABEL,
+  type PasswordInputProps,
+  type PasswordInputAPI,
+} from './password-input.js'
+
+export { passwordToggleVariants } from './password-input.styles.js'

package/dist/password-input/password-input.styles.ts

@@ -0,0 +1,10 @@
+import { cva } from '../shared/index.ts'
+
+/**
+ * Positioning classes for the reveal/hide toggle button rendered inside a
+ * password input's trailing padding. The wrapper must be `relative` and the
+ * input must reserve trailing space (e.g. `pr-10`).
+ */
+export const passwordToggleVariants = cva({
+  base: 'absolute right-2 top-1/2 flex size-7 -translate-y-1/2 items-center justify-center rounded-md text-muted-foreground transition-colors hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+})

package/dist/password-input/password-input.ts

@@ -0,0 +1,45 @@
+export interface PasswordInputProps {
+  /** Whether the password is currently revealed (shown as plain text). */
+  revealed?: boolean
+  /**
+   * Accessible label for the reveal (show password) action.
+   * @default 'Show password'
+   */
+  revealLabel?: string
+  /**
+   * Accessible label for the hide action.
+   * @default 'Hide password'
+   */
+  hideLabel?: string
+}
+
+export interface PasswordInputAPI {
+  /** The `type` attribute for the underlying input given the revealed state. */
+  inputType: 'text' | 'password'
+  /** The accessible label for the toggle button given the revealed state. */
+  toggleLabel: string
+  /** The `aria-pressed` value for the toggle button. */
+  togglePressed: boolean
+}
+
+export const DEFAULT_REVEAL_LABEL = 'Show password'
+export const DEFAULT_HIDE_LABEL = 'Hide password'
+
+/**
+ * State-free password-input helper. Given a `revealed` flag (owned by the
+ * framework adapter), it returns the input `type`, the toggle button's
+ * accessible label, and its `aria-pressed` value. It does not hold state.
+ */
+export function createPasswordInput(props: PasswordInputProps = {}): PasswordInputAPI {
+  const {
+    revealed = false,
+    revealLabel = DEFAULT_REVEAL_LABEL,
+    hideLabel = DEFAULT_HIDE_LABEL,
+  } = props
+
+  return {
+    inputType: revealed ? 'text' : 'password',
+    toggleLabel: revealed ? hideLabel : revealLabel,
+    togglePressed: revealed,
+  }
+}

package/dist/pre-call-lobby/index.ts

@@ -0,0 +1,22 @@
+export {
+  createPreCallLobby,
+  micLevelToBars,
+  type MediaDeviceOption,
+  type DeviceKind,
+  type PreCallLobbyProps,
+  type PreCallLobbyAPI,
+} from './pre-call-lobby.js'
+
+export {
+  preCallLobbyVariants,
+  preCallCameraVariants,
+  preCallCameraPlaceholderClass,
+  preCallDeviceRowClass,
+  preCallDeviceLabelClass,
+  preCallDeviceSelectClass,
+  preCallMicMeterClass,
+  preCallMicBarVariants,
+  preCallControlsRowClass,
+  preCallToggleVariants,
+  preCallJoinButtonClass,
+} from './pre-call-lobby.styles.js'