@refraction-ui/astro 0.12.0 → 0.13.0

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'

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

@@ -0,0 +1,74 @@
+/** Microphone state for a video participant. */
+export type VideoTileMicState = 'on' | 'muted'
+
+/** Data describing a video meeting participant tile. */
+export interface VideoTileData {
+  /** Unique participant identifier. */
+  id: string
+  /** Display name shown in the name chip. */
+  name: string
+  /** Current microphone state. Defaults to 'on'. */
+  micState?: VideoTileMicState
+  /** Whether the participant is currently speaking (active audio). */
+  speaking?: boolean
+  /** Whether the tile is pinned in the grid. */
+  pinned?: boolean
+}
+
+export interface VideoTileHeadlessProps {
+  /** Whether the participant is actively speaking. */
+  speaking?: boolean
+  /** Whether the tile is pinned in the grid. */
+  pinned?: boolean
+}
+
+export interface VideoTileAPI {
+  /** Data attributes for styling hooks — spread onto the tile container. */
+  dataAttributes: {
+    'data-speaking': string
+    'data-pinned': string
+  }
+  /** ARIA props — spread onto the tile container. */
+  ariaProps: {
+    role: 'group'
+  }
+}
+
+/**
+ * Derive framework-agnostic data attributes and ARIA props for a VideoTile.
+ *
+ * Adapters spread `dataAttributes` and `ariaProps` onto the tile container so
+ * CSS selectors and assistive technology can reflect the current participant
+ * state without coupling to a specific framework.
+ */
+export function createVideoTile(props: VideoTileHeadlessProps = {}): VideoTileAPI {
+  const { speaking = false, pinned = false } = props
+
+  return {
+    dataAttributes: {
+      'data-speaking': speaking ? 'true' : 'false',
+      'data-pinned': pinned ? 'true' : 'false',
+    },
+    ariaProps: {
+      role: 'group',
+    },
+  }
+}
+
+/**
+ * Derive up to two uppercase initials from a display name.
+ *
+ * Splits on whitespace and takes the first character of the first two words.
+ * Single-word names produce a single initial.
+ *
+ * @example
+ * getInitials('Maya Goldberg') // 'MG'
+ * getInitials('Alice')         // 'A'
+ */
+export function getInitials(name: string): string {
+  const words = name.trim().split(/\s+/).filter(Boolean)
+  return words
+    .slice(0, 2)
+    .map((w) => w[0].toUpperCase())
+    .join('')
+}

package/dist/wizard/index.ts

@@ -0,0 +1,28 @@
+export {
+  createWizard,
+  getStepState,
+  getNextIndex,
+  getPrevIndex,
+  canAdvance,
+  wizardProgress,
+  type WizardStep,
+  type WizardStepStatus,
+  type WizardStepState,
+  type WizardOrientation,
+  type WizardProps,
+  type WizardAPI,
+} from './wizard.js'
+
+export {
+  wizardVariants,
+  wizardRailVariants,
+  wizardStepItemVariants,
+  wizardStepIndicatorVariants,
+  wizardStepLabelVariants,
+  wizardStepOptionalClass,
+  wizardConnectorVariants,
+  wizardContentClass,
+  wizardFooterClass,
+  wizardPrimaryButtonVariants,
+  wizardSecondaryButtonVariants,
+} from './wizard.styles.js'