@refraction-ui/astro 0.12.0 → 0.14.0

package/dist/terminal/terminal.ts

@@ -0,0 +1,60 @@
+/** The semantic kind of a terminal output line. */
+export type TerminalLineKind = 'command' | 'stdout' | 'stderr' | 'info' | 'success'
+
+/** A single line displayed in the terminal output panel. */
+export interface TerminalLine {
+  /** Optional stable key for list rendering. */
+  id?: string
+  /** Semantic kind — drives styling and screen-reader announcements. */
+  kind: TerminalLineKind
+  /** Text content of the line. */
+  text: string
+}
+
+export interface TerminalAPI {
+  /**
+   * ARIA attributes to spread on the terminal container element.
+   * - `role="log"` semantics: assistive technologies announce appended content.
+   * - `aria-live="polite"` so new output does not interrupt the user mid-action.
+   */
+  ariaProps: {
+    role: 'log'
+    'aria-live': 'polite'
+    'aria-label'?: string
+  }
+  /** Data attributes for styling hooks. */
+  dataAttributes: Record<string, string>
+}
+
+/**
+ * Build the prompt string shown before a command line.
+ *
+ * @param promptSymbol - The shell prompt character(s), e.g. `'$'` or `'❯'`.
+ * @param command - The command text that follows the prompt.
+ * @returns The formatted prompt string, e.g. `'$ python solution.py'`.
+ */
+export function formatPrompt(promptSymbol: string, command: string): string {
+  return `${promptSymbol} ${command}`
+}
+
+/**
+ * Build the framework-agnostic ARIA and data props for a terminal output panel.
+ *
+ * Returns `role="log"` (live region semantics for streaming output) plus data
+ * attributes; adapters spread these onto their scroll container.
+ */
+export function createTerminal(options: { label?: string } = {}): TerminalAPI {
+  const ariaProps: TerminalAPI['ariaProps'] = {
+    role: 'log',
+    'aria-live': 'polite',
+  }
+  if (options.label) {
+    ariaProps['aria-label'] = options.label
+  }
+
+  const dataAttributes: Record<string, string> = {
+    'data-component': 'terminal',
+  }
+
+  return { ariaProps, dataAttributes }
+}

package/dist/test-results/index.ts

@@ -0,0 +1,19 @@
+export {
+  summarizeTests,
+  createTestResults,
+  type TestStatus,
+  type TestResultData,
+  type TestSummary,
+  type TestResultsAPI,
+} from './test-results.js'
+
+export {
+  testResultsContainerVariants,
+  testResultsSummaryVariants,
+  testRowVariants,
+  testStatusBadgeVariants,
+  testNameClass,
+  testDurationClass,
+  testDiffBlockVariants,
+  testMessageClass,
+} from './test-results.styles.js'

package/dist/test-results/test-results.styles.ts

@@ -0,0 +1,93 @@
+import { cva } from '../shared/index.ts'
+
+/** Outer container that wraps the summary bar and the test row list. */
+export const testResultsContainerVariants = cva({
+  base: 'flex flex-col gap-3 w-full',
+  variants: {},
+  defaultVariants: {},
+})
+
+/**
+ * Summary bar ("2 / 3 passed").
+ *
+ * The `outcome` variant maps to a semantic color token so the bar turns green
+ * when everything passes, red when there are failures.
+ */
+export const testResultsSummaryVariants = cva({
+  base: [
+    'flex items-center gap-2 rounded-md px-3 py-2 text-sm font-medium',
+    'border',
+  ].join(' '),
+  variants: {
+    outcome: {
+      pass: 'border-success/30 bg-success/10 text-success',
+      fail: 'border-destructive/30 bg-destructive/10 text-destructive',
+      skip: 'border-muted/30 bg-muted/10 text-muted-foreground',
+    },
+  },
+  defaultVariants: {
+    outcome: 'pass',
+  },
+})
+
+/** A single test row in the list. */
+export const testRowVariants = cva({
+  base: [
+    'flex flex-col gap-1.5 rounded-md border px-3 py-2.5 text-sm',
+  ].join(' '),
+  variants: {
+    status: {
+      pass: 'border-success/20 bg-success/5',
+      fail: 'border-destructive/20 bg-destructive/5',
+      skip: 'border-muted/20 bg-muted/5',
+    },
+  },
+  defaultVariants: {
+    status: 'pass',
+  },
+})
+
+/** Status icon / badge inside a test row (the PASS / FAIL / SKIP pill). */
+export const testStatusBadgeVariants = cva({
+  base: 'inline-flex items-center rounded px-1.5 py-0.5 text-xs font-semibold uppercase tracking-wide',
+  variants: {
+    status: {
+      pass: 'bg-success/20 text-success',
+      fail: 'bg-destructive/20 text-destructive',
+      skip: 'bg-muted text-muted-foreground',
+    },
+  },
+  defaultVariants: {
+    status: 'pass',
+  },
+})
+
+/** Test name text inside a row. */
+export const testNameClass = 'font-medium text-foreground'
+
+/** Duration text ("12 ms") inside a row. */
+export const testDurationClass = 'text-xs text-muted-foreground'
+
+/**
+ * Expected / actual diff block shown beneath a failing test row.
+ *
+ * The `side` variant sets the left-border accent color to distinguish the two
+ * sides of the diff.
+ */
+export const testDiffBlockVariants = cva({
+  base: [
+    'rounded border-l-2 bg-muted/30 px-3 py-2 font-mono text-xs text-foreground',
+  ].join(' '),
+  variants: {
+    side: {
+      expected: 'border-l-success text-success',
+      actual: 'border-l-destructive text-destructive',
+    },
+  },
+  defaultVariants: {
+    side: 'actual',
+  },
+})
+
+/** Error / skip message text beneath a test row. */
+export const testMessageClass = 'text-xs text-muted-foreground italic'

package/dist/test-results/test-results.ts

@@ -0,0 +1,83 @@
+import type { AccessibilityProps } from '../shared/index.ts'
+
+/** The execution status of a single test case. */
+export type TestStatus = 'pass' | 'fail' | 'skip'
+
+/** Data for a single test case result. */
+export interface TestResultData {
+  /** Unique identifier for the test. */
+  id: string
+  /** Human-readable test name. */
+  name: string
+  /** Execution status. */
+  status: TestStatus
+  /** How long the test took to run, in milliseconds. */
+  durationMs?: number
+  /** Expected value (shown in diff when the test fails). */
+  expected?: string
+  /** Actual value received (shown in diff when the test fails). */
+  actual?: string
+  /** Optional message — error message on failure, skip reason, etc. */
+  message?: string
+}
+
+/** Aggregate counts derived from a list of test results. */
+export interface TestSummary {
+  total: number
+  passed: number
+  failed: number
+  skipped: number
+  /** True when every test passed (failed === 0 and skipped === 0). */
+  allPassed: boolean
+}
+
+export interface TestResultsAPI {
+  /** ARIA attributes to spread on the list container (`role="list"`). */
+  ariaProps: Partial<AccessibilityProps>
+  /** Data attributes for styling hooks. */
+  dataAttributes: Record<string, string>
+}
+
+/**
+ * Compute aggregate summary counts from a list of {@link TestResultData}.
+ *
+ * Pure function — no side effects, safe to call during SSR.
+ */
+export function summarizeTests(results: TestResultData[]): TestSummary {
+  let passed = 0
+  let failed = 0
+  let skipped = 0
+
+  for (const r of results) {
+    if (r.status === 'pass') passed++
+    else if (r.status === 'fail') failed++
+    else skipped++
+  }
+
+  return {
+    total: results.length,
+    passed,
+    failed,
+    skipped,
+    allPassed: failed === 0 && skipped === 0 && results.length > 0,
+  }
+}
+
+/**
+ * Build the framework-agnostic container props for a test results list.
+ *
+ * Returns `role="list"` plus data attributes that adapters spread onto their
+ * container element. The adapter is responsible for rendering individual items
+ * with `role="listitem"`.
+ */
+export function createTestResults(): TestResultsAPI {
+  const ariaProps: Partial<AccessibilityProps> = {
+    role: 'list',
+  }
+
+  const dataAttributes: Record<string, string> = {
+    'data-component': 'test-results',
+  }
+
+  return { ariaProps, dataAttributes }
+}

package/dist/timeline/index.ts

@@ -0,0 +1,22 @@
+export {
+  createTimeline,
+  getTimelineItemAria,
+  resolveTimelineItems,
+  type TimelineOrientation,
+  type TimelineItemStatus,
+  type TimelineItemData,
+  type TimelineProps,
+  type TimelineAPI,
+} from './timeline.js'
+
+export {
+  timelineVariants,
+  timelineItemVariants,
+  timelineMarkerVariants,
+  timelineConnectorVariants,
+  timelineGutterClass,
+  timelineTimeClass,
+  timelineTitleClass,
+  timelineDescriptionClass,
+  timelineContentClass,
+} from './timeline.styles.js'

package/dist/timeline/timeline.styles.ts

@@ -0,0 +1,98 @@
+import { cva } from '../shared/index.ts'
+
+/**
+ * Outer rail / list container.
+ *
+ * Vertical: a single column; horizontal: a row so items sit side-by-side.
+ */
+export const timelineVariants = cva({
+  base: 'relative',
+  variants: {
+    orientation: {
+      vertical: 'flex flex-col',
+      horizontal: 'flex flex-row items-start overflow-x-auto',
+    },
+  },
+  defaultVariants: {
+    orientation: 'vertical',
+  },
+})
+
+/**
+ * A single event row / column.
+ *
+ * In vertical mode items stack with a left gutter for the marker + connector.
+ * In horizontal mode each item takes equal width and the connector runs above.
+ */
+export const timelineItemVariants = cva({
+  base: 'relative flex gap-4',
+  variants: {
+    orientation: {
+      vertical: 'flex-row pb-8 last:pb-0',
+      horizontal: 'flex-col items-center flex-1 px-2',
+    },
+  },
+  defaultVariants: {
+    orientation: 'vertical',
+  },
+})
+
+/**
+ * The marker / dot that represents the event on the rail.
+ *
+ * Status variants map directly to semantic token colours so theming is
+ * handled at the design-token level, not inline.
+ */
+export const timelineMarkerVariants = cva({
+  base: [
+    'relative z-10 flex shrink-0 items-center justify-center',
+    'size-3 rounded-full border-2',
+    'transition-colors',
+  ].join(' '),
+  variants: {
+    status: {
+      done: 'bg-primary border-primary',
+      current: 'bg-background border-primary ring-2 ring-primary ring-offset-2 ring-offset-background',
+      upcoming: 'bg-muted border-muted-foreground/30',
+      default: 'bg-background border-border',
+    },
+  },
+  defaultVariants: {
+    status: 'default',
+  },
+})
+
+/**
+ * The connector line drawn between adjacent markers.
+ *
+ * Vertical: a thin vertical stripe anchored to the left gutter.
+ * Horizontal: a thin horizontal stripe anchored above the content row.
+ * The last item hides its connector so the rail terminates cleanly.
+ */
+export const timelineConnectorVariants = cva({
+  base: 'absolute bg-border',
+  variants: {
+    orientation: {
+      vertical: 'left-[5px] top-3 w-0.5 h-full',
+      horizontal: 'top-[5px] left-1/2 w-full h-0.5',
+    },
+  },
+  defaultVariants: {
+    orientation: 'vertical',
+  },
+})
+
+/** Wrapper that holds the marker + connector in the gutter column/row. */
+export const timelineGutterClass = 'relative flex flex-col items-center'
+
+/** Time / date label rendered near the marker. */
+export const timelineTimeClass = 'text-xs text-muted-foreground tabular-nums'
+
+/** Primary event title. */
+export const timelineTitleClass = 'text-sm font-medium text-foreground leading-snug'
+
+/** Secondary description text. */
+export const timelineDescriptionClass = 'mt-0.5 text-xs text-muted-foreground leading-relaxed'
+
+/** Content block (title + description) next to or below the marker. */
+export const timelineContentClass = 'flex flex-col min-w-0'

package/dist/timeline/timeline.ts

@@ -0,0 +1,86 @@
+import type { AccessibilityProps } from '../shared/index.ts'
+
+/** Layout orientation of the timeline. */
+export type TimelineOrientation = 'vertical' | 'horizontal'
+
+/** Visual status of a single timeline item. */
+export type TimelineItemStatus = 'done' | 'current' | 'upcoming' | 'default'
+
+/** Data describing a single event in the timeline. */
+export interface TimelineItemData {
+  /** Unique identifier for the item. */
+  id: string
+  /** Primary label shown beside the marker. */
+  title: string
+  /** Optional timestamp / date string shown near the marker. */
+  time?: string
+  /** Additional detail text rendered below the title. */
+  description?: string
+  /** Visual status of this item. Defaults to `'default'` when omitted. */
+  status?: TimelineItemStatus
+}
+
+export interface TimelineProps {
+  /** Ordered list of events to display. */
+  items: TimelineItemData[]
+  /** Layout direction. */
+  orientation?: TimelineOrientation
+}
+
+export interface TimelineAPI {
+  /** ARIA attributes to spread on the list container (`role="list"`). */
+  ariaProps: Partial<AccessibilityProps>
+  /** Data attributes for styling hooks. */
+  dataAttributes: Record<string, string>
+}
+
+/**
+ * Build the framework-agnostic container props for a timeline.
+ *
+ * Returns `role="list"` (the items carry `role="listitem"`) plus a
+ * `data-orientation` attribute. The function is JSX-free so it can run in
+ * any environment including server-side Node and Astro SSR.
+ */
+export function createTimeline(
+  props: Pick<TimelineProps, 'orientation'> = {},
+): TimelineAPI {
+  const { orientation = 'vertical' } = props
+
+  const ariaProps: Partial<AccessibilityProps> = {
+    role: 'list',
+  }
+
+  const dataAttributes: Record<string, string> = {
+    'data-orientation': orientation,
+  }
+
+  return { ariaProps, dataAttributes }
+}
+
+/**
+ * Accessibility props for a single timeline item.
+ *
+ * Every item gets `role="listitem"` regardless of status so screen readers
+ * announce the full list correctly.
+ */
+export function getTimelineItemAria(): Partial<AccessibilityProps> {
+  return { role: 'listitem' }
+}
+
+/**
+ * Normalise a raw list of timeline items so every entry has an explicit
+ * `status`. Items without a status receive `'default'`.
+ *
+ * This is the single source of truth shared by every adapter — call it once
+ * at render time and iterate over the result.
+ */
+export function resolveTimelineItems(
+  items: TimelineItemData[],
+): Required<TimelineItemData>[] {
+  return items.map((item) => ({
+    ...item,
+    status: item.status ?? 'default',
+    time: item.time ?? '',
+    description: item.description ?? '',
+  }))
+}

package/dist/video-grid/index.ts

@@ -0,0 +1,16 @@
+export {
+  createVideoGrid,
+  computeGridColumns,
+  bucketByCount,
+  type VideoGridLayout,
+  type VideoGridBucket,
+  type VideoGridHeadlessProps,
+  type VideoGridAPI,
+} from './video-grid.js'
+
+export {
+  videoGridVariants,
+  videoGridSpotlightClass,
+  videoGridFilmstripClass,
+  videoGridFilmstripTileClass,
+} from './video-grid.styles.js'

package/dist/video-grid/video-grid.styles.ts

@@ -0,0 +1,38 @@
+import { cva } from '../shared/index.ts'
+
+/**
+ * Grid container variants.
+ *
+ * - `layout: 'grid'`    — uniform CSS grid; column count is set inline by the
+ *   adapter using `computeGridColumns` (gridTemplateColumns).
+ * - `layout: 'speaker'` — two-row layout: large spotlight on top, filmstrip row
+ *   below. The adapter renders the spotlight as the first child and a horizontal
+ *   overflow row for remaining tiles.
+ */
+export const videoGridVariants = cva({
+  base: 'w-full h-full gap-2',
+  variants: {
+    layout: {
+      grid: 'grid',
+      speaker: 'flex flex-col',
+      auto: 'grid',
+    },
+  },
+  defaultVariants: {
+    layout: 'auto',
+  },
+})
+
+/** Full-bleed spotlight area in speaker view (takes up remaining vertical space). */
+export const videoGridSpotlightClass = 'relative flex-1 min-h-0 rounded-xl overflow-hidden bg-muted'
+
+/**
+ * Horizontal filmstrip row used in speaker view.
+ * Each tile in this row is constrained to a fixed width so the row scrolls
+ * rather than wraps on large calls.
+ */
+export const videoGridFilmstripClass =
+  'flex flex-row gap-2 overflow-x-auto py-1 shrink-0'
+
+/** Individual filmstrip tile wrapper — fixed width so they don't collapse. */
+export const videoGridFilmstripTileClass = 'w-36 shrink-0'

package/dist/video-grid/video-grid.ts

@@ -0,0 +1,93 @@
+/**
+ * Layout mode for a VideoGrid.
+ *
+ * - 'auto'    — choose grid or speaker view based on participant count (≤1 forces speaker)
+ * - 'grid'    — always render an even CSS grid of tiles
+ * - 'speaker' — render one large spotlight tile + a filmstrip row for the rest
+ */
+export type VideoGridLayout = 'auto' | 'grid' | 'speaker'
+
+/**
+ * Bucket label that describes the rough meeting size.
+ * Useful for analytics and adaptive UI decisions.
+ */
+export type VideoGridBucket =
+  | 'solo'
+  | 'pair'
+  | 'small'
+  | 'medium'
+  | 'large'
+  | 'townhall'
+
+export interface VideoGridHeadlessProps {
+  /** Desired layout mode. */
+  layout?: VideoGridLayout
+}
+
+export interface VideoGridAPI {
+  /** ARIA attributes to spread on the grid container. */
+  ariaProps: {
+    role: 'group'
+  }
+  /** Data attributes for CSS styling hooks. */
+  dataAttributes: {
+    'data-layout': VideoGridLayout
+    'data-count'?: string
+  }
+}
+
+/**
+ * Compute the number of CSS grid columns for N participants.
+ *
+ * The responsive rule mirrors easyloops meeting layouts:
+ *
+ * | count | columns |
+ * |-------|---------|
+ * | 1     | 1       |
+ * | 2     | 2       |
+ * | 3–4   | 2       |
+ * | 5–9   | 3       |
+ * | 10–16 | 4       |
+ * | 17–25 | 5       |
+ * | 26+   | 6       |
+ */
+export function computeGridColumns(count: number): number {
+  if (count <= 1) return 1
+  if (count <= 4) return 2
+  if (count <= 9) return 3
+  if (count <= 16) return 4
+  if (count <= 25) return 5
+  return 6
+}
+
+/**
+ * Label the meeting size as a human-readable bucket.
+ *
+ * Useful for analytics events and adaptive UI decisions without
+ * coupling to the exact column math.
+ */
+export function bucketByCount(count: number): VideoGridBucket {
+  if (count <= 1) return 'solo'
+  if (count <= 2) return 'pair'
+  if (count <= 9) return 'small'
+  if (count <= 16) return 'medium'
+  if (count <= 25) return 'large'
+  return 'townhall'
+}
+
+/**
+ * Build the framework-agnostic ARIA and data attributes for a VideoGrid
+ * container.  Adapters spread these onto their host element.
+ */
+export function createVideoGrid(props: VideoGridHeadlessProps = {}): VideoGridAPI {
+  const { layout = 'auto' } = props
+
+  return {
+    ariaProps: {
+      role: 'group',
+    },
+    dataAttributes: {
+      'data-layout': layout,
+    },
+  }
+}

package/dist/video-tile/index.ts

@@ -0,0 +1,17 @@
+export {
+  createVideoTile,
+  getInitials,
+  type VideoTileMicState,
+  type VideoTileData,
+  type VideoTileHeadlessProps,
+  type VideoTileAPI,
+} from './video-tile.js'
+
+export {
+  videoTileVariants,
+  videoTileNameChipClass,
+  videoTileMicIconClass,
+  videoTileAvatarFallbackClass,
+  videoTileAvatarCircleClass,
+  videoTileReactionBadgeClass,
+} from './video-tile.styles.js'

package/dist/video-tile/video-tile.styles.ts

@@ -0,0 +1,59 @@
+import { cva } from '../shared/index.ts'
+
+/**
+ * Root tile container — aspect-video, rounded corners, clipped media.
+ *
+ * `speaking` variant adds a visible ring to indicate active audio.
+ * `pinned` variant adds a stronger ring to mark a pinned participant.
+ *
+ * cva boolean-like variants use string values ('true'/'false') per the
+ * refraction-ui convention — callers must pass strings, not raw booleans.
+ */
+export const videoTileVariants = cva({
+  base: [
+    'relative aspect-video overflow-hidden rounded-lg bg-muted',
+    'transition-shadow duration-200',
+  ].join(' '),
+  variants: {
+    speaking: {
+      'true': 'ring-2 ring-emerald-500 dark:ring-emerald-400 ring-offset-2 ring-offset-background',
+      'false': '',
+    },
+    pinned: {
+      'true': 'ring-2 ring-primary ring-offset-2 ring-offset-background',
+      'false': '',
+    },
+  },
+  defaultVariants: {
+    speaking: 'false',
+    pinned: 'false',
+  },
+})
+
+/**
+ * Name chip anchored to the bottom-left of the tile.
+ * Semi-transparent bg keeps it legible over any media content.
+ */
+export const videoTileNameChipClass =
+  'absolute bottom-2 left-2 flex items-center gap-1.5 rounded-md bg-background/70 px-2 py-0.5 text-xs font-medium text-foreground backdrop-blur-sm'
+
+/**
+ * Mic-muted icon container — sits inside the name chip at the trailing edge.
+ */
+export const videoTileMicIconClass = 'text-destructive'
+
+/**
+ * Avatar fallback circle — centred in the tile when no media stream is available.
+ */
+export const videoTileAvatarFallbackClass =
+  'absolute inset-0 flex items-center justify-center'
+
+/** Inner circle with initials. */
+export const videoTileAvatarCircleClass =
+  'flex size-16 items-center justify-center rounded-full bg-card text-foreground text-xl font-semibold select-none'
+
+/**
+ * Reaction badge slot — anchored to the top-right corner.
+ */
+export const videoTileReactionBadgeClass =
+  'absolute right-2 top-2 flex items-center justify-center rounded-full bg-background/70 px-1.5 py-0.5 text-sm backdrop-blur-sm'