@refraction-ui/astro 0.12.0 → 0.14.0

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

@@ -0,0 +1,45 @@
+import { cva } from '../shared/index.ts'
+
+/**
+ * Caption overlay container — an absolute-friendly, translucent dark surface
+ * centred over its positioned ancestor (e.g. a video element).
+ */
+export const liveCaptionsVariants = cva({
+  base: [
+    'relative mx-auto w-full max-w-2xl rounded-xl',
+    'bg-card/80 backdrop-blur-sm',
+    'px-4 py-3 space-y-1',
+  ].join(' '),
+  variants: {
+    /** Controls how the container is positioned in the layout. */
+    position: {
+      /** Sits in normal document flow (default). */
+      static: '',
+      /** Absolutely positioned — consumer places it with inset utilities. */
+      absolute: 'absolute',
+    },
+  },
+  defaultVariants: {
+    position: 'static',
+  },
+})
+
+/**
+ * A single cue line inside the overlay.
+ * Non-final (interim) cues get a dimmed italic treatment to signal they may change.
+ */
+export const liveCaptionsCueVariants = cva({
+  base: 'text-sm leading-snug text-foreground',
+  variants: {
+    interim: {
+      true: 'opacity-60 italic',
+      false: '',
+    },
+  },
+  defaultVariants: {
+    interim: 'false',
+  },
+})
+
+/** Speaker-name prefix — rendered slightly muted to distinguish it from the speech text. */
+export const liveCaptionsSpeakerClass = 'font-medium text-muted-foreground'

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/marquee-strip/index.ts

@@ -0,0 +1,14 @@
+export {
+  createMarqueeStrip,
+  type MarqueeStripProps,
+  type MarqueeStripAPI,
+} from './marquee-strip.js'
+
+export {
+  marqueeStripVariants,
+  marqueeStripInnerClass,
+  marqueeStripScrollOuterClass,
+  marqueeStripScrollTrackClass,
+  marqueeStripLabelClass,
+  marqueeStripItemClass,
+} from './marquee-strip.styles.js'

package/dist/marquee-strip/marquee-strip.styles.ts

@@ -0,0 +1,61 @@
+import { cva } from '../shared/index.ts'
+
+/**
+ * Container — a full-width band with a subtle muted background and border.
+ *
+ * The `scroll` variant switches the inner track from wrapping flex to an
+ * overflow-hidden marquee track. See {@link marqueeStripInnerClass} and
+ * {@link marqueeStripScrollTrackClass} for the corresponding track classes.
+ */
+export const marqueeStripVariants = cva({
+  base: 'w-full bg-muted/30 border-y border-border py-3',
+  variants: {
+    scroll: {
+      true: '',
+      false: '',
+    },
+  },
+  defaultVariants: {
+    scroll: 'false',
+  },
+})
+
+/**
+ * Inner wrapper for static (non-scroll) mode.
+ *
+ * Items wrap naturally so they never overflow on narrow viewports.
+ */
+export const marqueeStripInnerClass =
+  'flex flex-wrap items-center gap-3 px-4'
+
+/**
+ * Outer clip track for scroll mode — hides overflow so the looping animation
+ * is invisible at the edges.
+ */
+export const marqueeStripScrollOuterClass = 'overflow-hidden px-4'
+
+/**
+ * Moving track for scroll mode.
+ *
+ * The `marquee` keyframe must be defined in the consuming app's global CSS
+ * (or via a Tailwind plugin). The canonical definition is:
+ *
+ * ```css
+ * @keyframes marquee {
+ *   from { transform: translateX(0); }
+ *   to   { transform: translateX(-50%); }
+ * }
+ * ```
+ *
+ * Items are duplicated once by the adapter so the strip appears seamless
+ * (the track is effectively 200 % wide and translates to –50 %).
+ */
+export const marqueeStripScrollTrackClass =
+  'flex items-center gap-3 w-max animate-[marquee_30s_linear_infinite]'
+
+/** Strip label — shown before the items (uppercase eyebrow style). */
+export const marqueeStripLabelClass =
+  'text-xs font-semibold uppercase tracking-widest text-muted-foreground shrink-0'
+
+/** Individual item text. */
+export const marqueeStripItemClass = 'text-sm text-foreground'

package/dist/marquee-strip/marquee-strip.ts

@@ -0,0 +1,35 @@
+import type { AccessibilityProps } from '../shared/index.ts'
+
+export interface MarqueeStripProps {
+  /** Whether to continuously scroll the items. */
+  scroll?: boolean
+}
+
+export interface MarqueeStripAPI {
+  /** ARIA attributes to spread on the container element (`role="group"`). */
+  ariaProps: Partial<AccessibilityProps>
+  /** Data attributes for styling hooks. */
+  dataAttributes: Record<string, string>
+}
+
+/**
+ * Build the framework-agnostic container props for a marquee strip.
+ *
+ * Returns `role="group"` plus a `data-scroll` attribute. Adapters spread these
+ * onto their container and render the label and items themselves. In scroll mode
+ * the adapter is responsible for duplicating items once to achieve a seamless
+ * loop (the CSS `marquee` keyframe translates from 0 to –50%).
+ */
+export function createMarqueeStrip(props: MarqueeStripProps = {}): MarqueeStripAPI {
+  const { scroll = false } = props
+
+  const ariaProps: Partial<AccessibilityProps> = {
+    role: 'group',
+  }
+
+  const dataAttributes: Record<string, string> = {
+    'data-scroll': String(scroll),
+  }
+
+  return { ariaProps, dataAttributes }
+}

package/dist/mastery-bar/index.ts

@@ -0,0 +1,15 @@
+export {
+  clampPercent,
+  createMasteryBar,
+  type MasteryBarSize,
+  type MasteryBarProps,
+  type MasteryBarAPI,
+} from './mastery-bar.js'
+
+export {
+  masteryBarVariants,
+  masteryBarFillVariants,
+  masteryBarLabelClass,
+  masteryBarLeadingLabelClass,
+  masteryBarHeaderClass,
+} from './mastery-bar.styles.js'

package/dist/mastery-bar/mastery-bar.styles.ts

@@ -0,0 +1,45 @@
+import { cva } from '../shared/index.ts'
+
+/**
+ * Track (outer container): rounded, muted background.
+ * `size` variant controls the track height.
+ */
+export const masteryBarVariants = cva({
+  base: 'w-full overflow-hidden rounded-full bg-muted',
+  variants: {
+    size: {
+      sm: 'h-1.5',
+      md: 'h-2',
+      lg: 'h-3',
+    },
+  },
+  defaultVariants: {
+    size: 'md',
+  },
+})
+
+/**
+ * Fill (inner bar): rounded, primary background.
+ * `muted` variant renders at reduced opacity for secondary/inactive states.
+ */
+export const masteryBarFillVariants = cva({
+  base: 'h-full rounded-full bg-primary',
+  variants: {
+    muted: {
+      true: 'bg-primary/70',
+      false: 'bg-primary',
+    },
+  },
+  defaultVariants: {
+    muted: 'false',
+  },
+})
+
+/** Class applied to each text label (leading or trailing). */
+export const masteryBarLabelClass = 'text-xs text-muted-foreground'
+
+/** Class for the leading (left-side) label. */
+export const masteryBarLeadingLabelClass = 'text-xs text-muted-foreground'
+
+/** Header row above the track: leading label on the left, label on the right. */
+export const masteryBarHeaderClass = 'flex justify-between items-baseline mb-1'

package/dist/mastery-bar/mastery-bar.ts

@@ -0,0 +1,55 @@
+/** Visual size of a mastery bar. */
+export type MasteryBarSize = 'sm' | 'md' | 'lg'
+
+export interface MasteryBarProps {
+  /** Progress value (0–100). Values outside this range are clamped. */
+  value: number
+  /** Label shown on the right side of the header row. */
+  label?: string
+  /** Label shown on the left side of the header row. */
+  leadingLabel?: string
+  /** Visual size of the track. */
+  size?: MasteryBarSize
+  /** Renders the fill at reduced opacity to indicate a muted/secondary state. */
+  muted?: boolean
+}
+
+export interface MasteryBarAPI {
+  /** ARIA attributes to spread on the progressbar element. */
+  ariaProps: Record<string, string | number | boolean>
+  /** Data attributes for styling hooks. */
+  dataAttributes: Record<string, string>
+}
+
+/**
+ * Clamp a raw numeric value to the [0, 100] range.
+ *
+ * Values below 0 become 0; values above 100 become 100; NaN is treated as 0.
+ */
+export function clampPercent(value: number): number {
+  if (Number.isNaN(value)) return 0
+  return Math.min(100, Math.max(0, value))
+}
+
+/**
+ * Build the framework-agnostic progressbar props for a mastery bar.
+ *
+ * Returns `role="progressbar"` ARIA attributes plus data attributes; adapters
+ * spread these onto their track element.
+ */
+export function createMasteryBar({ value }: Pick<MasteryBarProps, 'value'>): MasteryBarAPI {
+  const clamped = clampPercent(value)
+
+  const ariaProps: Record<string, string | number | boolean> = {
+    role: 'progressbar',
+    'aria-valuenow': clamped,
+    'aria-valuemin': 0,
+    'aria-valuemax': 100,
+  }
+
+  const dataAttributes: Record<string, string> = {
+    'data-value': String(clamped),
+  }
+
+  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'