@refraction-ui/astro 0.12.0 → 0.13.0

package/dist/radial-gauge/radial-gauge.ts

@@ -0,0 +1,183 @@
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** The visual size of the gauge. */
+export type GaugeSize = 'sm' | 'md' | 'lg'
+
+/** Tone mapped to a zone range. */
+export type GaugeTone = 'default' | 'success' | 'warning' | 'danger'
+
+/**
+ * A threshold zone that applies a semantic tone when the gauge value falls
+ * at or below `upTo`. Zones should be listed in ascending `upTo` order; the
+ * first zone whose `upTo >= value` wins.
+ */
+export interface GaugeZone {
+  /** Value up to (and including) which this zone applies. */
+  upTo: number
+  /** Semantic tone for the arc while the value is in this zone. */
+  tone: GaugeTone
+}
+
+export interface RadialGaugeProps {
+  /** Current gauge value. */
+  value: number
+  /** Minimum possible value. */
+  min?: number
+  /** Maximum possible value. */
+  max?: number
+  /** Visual size. */
+  size?: GaugeSize
+}
+
+export interface RadialGaugeAPI {
+  /** ARIA attributes to spread on the SVG element (`role="meter"`). */
+  ariaProps: Record<string, string | number>
+  /** Data attributes for styling hooks. */
+  dataAttributes: Record<string, string>
+}
+
+// ---------------------------------------------------------------------------
+// Pixel diameters for each size variant (exported for use in adapters)
+// ---------------------------------------------------------------------------
+export const GAUGE_SIZE_PX: Record<GaugeSize, number> = {
+  sm: 80,
+  md: 120,
+  lg: 160,
+}
+
+// ---------------------------------------------------------------------------
+// Pure geometry helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Clamp `value` to the inclusive range `[min, max]`.
+ */
+export function clampValue(value: number, min: number, max: number): number {
+  return Math.min(Math.max(value, min), max)
+}
+
+/**
+ * Map a `value` within `[min, max]` to a fraction in `[0, 1]`.
+ * Returns 0 when `min === max` to avoid division by zero.
+ */
+export function valueToFraction(value: number, min: number, max: number): number {
+  if (max === min) return 0
+  return clampValue((value - min) / (max - min), 0, 1)
+}
+
+/**
+ * Convert polar coordinates to Cartesian.
+ * `angleDeg` is measured clockwise from the positive x-axis (SVG convention).
+ */
+export function polarToCartesian(
+  cx: number,
+  cy: number,
+  r: number,
+  angleDeg: number,
+): { x: number; y: number } {
+  const rad = ((angleDeg - 90) * Math.PI) / 180
+  return {
+    x: cx + r * Math.cos(rad),
+    y: cy + r * Math.sin(rad),
+  }
+}
+
+/**
+ * Build an SVG arc path `d` string from `startAngleDeg` to `endAngleDeg`
+ * (both measured clockwise from the top / 12-o'clock position).
+ *
+ * Returns an empty string when the arc span is zero.
+ */
+export function describeArc(
+  cx: number,
+  cy: number,
+  r: number,
+  startAngleDeg: number,
+  endAngleDeg: number,
+): string {
+  const span = endAngleDeg - startAngleDeg
+  if (span === 0) return ''
+
+  // For a full circle we need two arcs to avoid SVG treating start === end as
+  // a no-op.  Shift the end by 0.001° so the path stays valid.
+  const clampedEnd = span >= 360 ? startAngleDeg + 359.999 : endAngleDeg
+
+  const start = polarToCartesian(cx, cy, r, startAngleDeg)
+  const end = polarToCartesian(cx, cy, r, clampedEnd)
+  const largeArc = clampedEnd - startAngleDeg > 180 ? 1 : 0
+
+  return [
+    `M ${start.x} ${start.y}`,
+    `A ${r} ${r} 0 ${largeArc} 1 ${end.x} ${end.y}`,
+  ].join(' ')
+}
+
+/**
+ * Compute the `stroke-dashoffset` for a full-circle ring gauge.
+ *
+ * With `stroke-dasharray="circumference circumference"` and this offset, the
+ * visible portion of the stroke equals `fraction × circumference`.
+ */
+export function gaugeStrokeDashoffset(fraction: number, circumference: number): number {
+  return circumference * (1 - fraction)
+}
+
+// ---------------------------------------------------------------------------
+// Zone resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Find the active zone tone for the current `value`.
+ * Zones are tested in ascending `upTo` order; the first zone whose
+ * `upTo >= value` wins. Falls back to `'default'` when no zone matches.
+ */
+export function resolveZoneTone(
+  value: number,
+  zones: GaugeZone[],
+  _max: number,
+): GaugeTone {
+  if (!zones || zones.length === 0) return 'default'
+
+  // Sort a copy ascending by upTo so callers don't have to pre-sort.
+  const sorted = [...zones].sort((a, b) => a.upTo - b.upTo)
+
+  for (const zone of sorted) {
+    if (value <= zone.upTo) return zone.tone
+  }
+
+  // Value is above all zone thresholds — use the last zone's tone.
+  return sorted[sorted.length - 1].tone
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the framework-agnostic props for a radial gauge element.
+ *
+ * Returns `role="meter"` plus ARIA value attributes and data attributes;
+ * adapters spread these onto their `<svg>` element.
+ */
+export function createRadialGauge(props: RadialGaugeProps): RadialGaugeAPI {
+  const { value, min = 0, max = 100, size = 'md' } = props
+
+  const clamped = clampValue(value, min, max)
+
+  const ariaProps: Record<string, string | number> = {
+    role: 'meter',
+    'aria-valuenow': clamped,
+    'aria-valuemin': min,
+    'aria-valuemax': max,
+  }
+
+  const dataAttributes: Record<string, string> = {
+    'data-size': size,
+    'data-value': String(clamped),
+  }
+
+  return { ariaProps, dataAttributes }
+}

package/dist/rating-scale/index.ts

@@ -0,0 +1,16 @@
+export {
+  createRatingScale,
+  resolveRatingPoints,
+  getNextRatingIndex,
+  type RatingScaleSize,
+  type RatingScalePoint,
+  type RatingScaleProps,
+  type RatingScaleAPI,
+} from './rating-scale.js'
+
+export {
+  ratingScaleVariants,
+  ratingScaleTrackClass,
+  ratingScaleItemVariants,
+  ratingScaleLabelClass,
+} from './rating-scale.styles.js'

package/dist/rating-scale/rating-scale.styles.ts

@@ -0,0 +1,48 @@
+import { cva } from '../shared/index.ts'
+
+/** Container row that holds the points plus optional end labels. */
+export const ratingScaleVariants = cva({
+  base: 'inline-flex items-center gap-3',
+  variants: {
+    size: {
+      sm: '',
+      md: '',
+    },
+  },
+  defaultVariants: {
+    size: 'md',
+  },
+})
+
+/** Row of point buttons (the scale itself, between the end labels). */
+export const ratingScaleTrackClass = 'inline-flex items-center gap-1.5'
+
+/**
+ * A single point button. The `state` variant carries the selected vs unselected
+ * treatment so adapters never inline these classes.
+ */
+export const ratingScaleItemVariants = cva({
+  base: [
+    'inline-flex items-center justify-center rounded-md border font-medium tabular-nums',
+    'transition-colors focus-visible:outline-none focus-visible:ring-2',
+    'focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background',
+    'disabled:pointer-events-none disabled:opacity-50',
+  ].join(' '),
+  variants: {
+    size: {
+      sm: 'size-8 text-xs',
+      md: 'size-10 text-sm',
+    },
+    state: {
+      checked: 'border-primary bg-primary text-primary-foreground',
+      unchecked: 'border-input bg-background text-foreground hover:bg-accent hover:text-accent-foreground',
+    },
+  },
+  defaultVariants: {
+    size: 'md',
+    state: 'unchecked',
+  },
+})
+
+/** End-label text flanking the scale (e.g. "Never seen this" / "Could write it"). */
+export const ratingScaleLabelClass = 'text-xs text-muted-foreground'

package/dist/rating-scale/rating-scale.ts

@@ -0,0 +1,101 @@
+import type { AccessibilityProps } from '../shared/index.ts'
+
+/** Visual size of a rating scale. */
+export type RatingScaleSize = 'sm' | 'md'
+
+/** A single selectable point on the scale (1-indexed value + accessible label). */
+export interface RatingScalePoint {
+  /** The value this point represents. */
+  value: number
+  /** Accessible label for the point (falls back to the value). */
+  label?: string
+}
+
+export interface RatingScaleProps {
+  /** Currently selected value (controlled). */
+  value?: number
+  /** Number of points on the scale. Ignored when {@link points} is given. */
+  count?: number
+  /** Visual size. */
+  size?: RatingScaleSize
+}
+
+export interface RatingScaleAPI {
+  /** ARIA attributes to spread on the group element (`role="radiogroup"`). */
+  ariaProps: Partial<AccessibilityProps>
+  /** Data attributes for styling hooks. */
+  dataAttributes: Record<string, string>
+}
+
+/**
+ * Build the framework-agnostic group props for a rating / Likert scale.
+ *
+ * Returns `role="radiogroup"` plus data attributes; adapters spread these onto
+ * their container and render the points themselves. A rating scale is a
+ * single-select control with radio semantics, like a segmented control, but
+ * tuned for ordinal self-rating (e.g. a 1–5 Likert prompt with end labels).
+ */
+export function createRatingScale(props: RatingScaleProps = {}): RatingScaleAPI {
+  const { value, size = 'md' } = props
+
+  const ariaProps: Partial<AccessibilityProps> = {
+    role: 'radiogroup',
+  }
+
+  const dataAttributes: Record<string, string> = {
+    'data-size': size,
+  }
+  if (value !== undefined) {
+    dataAttributes['data-value'] = String(value)
+  }
+
+  return { ariaProps, dataAttributes }
+}
+
+/**
+ * Resolve the list of points for a scale from either an explicit list or a
+ * `count` (producing `1..count`). The single source of truth shared by every
+ * adapter so a `count={5}` scale renders identical points everywhere.
+ */
+export function resolveRatingPoints(
+  points: RatingScalePoint[] | undefined,
+  count = 5,
+): RatingScalePoint[] {
+  if (points && points.length > 0) return points
+  return Array.from({ length: Math.max(0, count) }, (_, i) => ({ value: i + 1 }))
+}
+
+/**
+ * Pure keyboard-navigation rule shared by every adapter.
+ *
+ * Unlike a wrapping segmented control, an ordinal rating scale **clamps** at
+ * the ends (you can't wrap from "5 — strongly agree" back to "1"). Home/End
+ * jump to the extremes; unhandled keys return `current` unchanged.
+ *
+ * - ArrowRight / ArrowUp   → next (clamped to last)
+ * - ArrowLeft  / ArrowDown → previous (clamped to first)
+ * - Home                   → first
+ * - End                    → last
+ */
+export function getNextRatingIndex(
+  current: number,
+  key: string,
+  count: number,
+): number {
+  if (count <= 0) return current
+
+  switch (key) {
+    case 'ArrowRight':
+    case 'ArrowUp':
+      return Math.min(current + 1, count - 1)
+    case 'ArrowLeft':
+    case 'ArrowDown':
+      return Math.max(current - 1, 0)
+    case 'Home':
+      return 0
+    case 'End':
+      return count - 1
+    default:
+      return current
+  }
+}

package/dist/sticky-note/index.ts

@@ -0,0 +1,14 @@
+export {
+  STICKY_NOTE_COLORS,
+  nextStickyColor,
+  createStickyNote,
+  type StickyNoteColor,
+  type CreateStickyNoteOptions,
+  type StickyNoteAPI,
+} from './sticky-note.js'
+
+export {
+  stickyNoteVariants,
+  stickyNoteTextClass,
+  stickyNoteAuthorClass,
+} from './sticky-note.styles.js'

package/dist/sticky-note/sticky-note.styles.ts

@@ -0,0 +1,37 @@
+import { cva } from '../shared/index.ts'
+
+/**
+ * Note container with color variant.
+ *
+ * Sticky notes are intrinsically colorful — an approved exception to the
+ * semantic-token-only rule. Each color maps to a soft tint background with a
+ * readable dark text.
+ */
+export const stickyNoteVariants = cva({
+  base: [
+    'relative inline-flex flex-col gap-2 rounded-md p-4',
+    'shadow-md',
+    'min-w-[160px] min-h-[120px]',
+  ].join(' '),
+  variants: {
+    color: {
+      yellow: 'bg-yellow-100 text-yellow-900',
+      pink: 'bg-pink-100 text-pink-900',
+      blue: 'bg-blue-100 text-blue-900',
+      green: 'bg-green-100 text-green-900',
+      purple: 'bg-purple-100 text-purple-900',
+      orange: 'bg-orange-100 text-orange-900',
+    },
+  },
+  defaultVariants: {
+    color: 'yellow',
+  },
+})
+
+/** Class for the editable/static text area inside the note. */
+export const stickyNoteTextClass =
+  'flex-1 w-full resize-none bg-transparent text-sm leading-relaxed placeholder:opacity-60 outline-none'
+
+/** Class for the author chip rendered in the note footer. */
+export const stickyNoteAuthorClass =
+  'mt-auto text-xs font-medium opacity-70 truncate'

package/dist/sticky-note/sticky-note.ts

@@ -0,0 +1,47 @@
+/** The available color variants for a sticky note. */
+export type StickyNoteColor = 'yellow' | 'pink' | 'blue' | 'green' | 'purple' | 'orange'
+
+/** Ordered list of all sticky note colors — used for cycling and iteration. */
+export const STICKY_NOTE_COLORS: StickyNoteColor[] = [
+  'yellow',
+  'pink',
+  'blue',
+  'green',
+  'purple',
+  'orange',
+]
+
+/**
+ * Returns the next color in the cycle. Wraps from the last color back to the
+ * first. Useful for "add note" flows that auto-assign colors in sequence.
+ */
+export function nextStickyColor(color: StickyNoteColor): StickyNoteColor {
+  const index = STICKY_NOTE_COLORS.indexOf(color)
+  const next = (index + 1) % STICKY_NOTE_COLORS.length
+  return STICKY_NOTE_COLORS[next]
+}
+
+export interface CreateStickyNoteOptions {
+  /** Color of the note. */
+  color: StickyNoteColor
+}
+
+export interface StickyNoteAPI {
+  /** Data attributes for styling hooks; spread onto the note container. */
+  dataAttributes: { 'data-color': StickyNoteColor }
+  /** ARIA props for the note container. */
+  ariaProps: { role: 'group' }
+}
+
+/**
+ * Build the framework-agnostic props for a sticky note container.
+ *
+ * Returns `role="group"` plus the `data-color` attribute that adapters use
+ * as a styling hook. Logic is pure and SSR-safe — no Math.random, no Date.
+ */
+export function createStickyNote(options: CreateStickyNoteOptions): StickyNoteAPI {
+  return {
+    dataAttributes: { 'data-color': options.color },
+    ariaProps: { role: 'group' },
+  }
+}

package/dist/terminal/index.ts

@@ -0,0 +1,13 @@
+export {
+  formatPrompt,
+  createTerminal,
+  type TerminalLineKind,
+  type TerminalLine,
+  type TerminalAPI,
+} from './terminal.js'
+
+export {
+  terminalVariants,
+  terminalLineVariants,
+  terminalPromptClass,
+} from './terminal.styles.js'

package/dist/terminal/terminal.styles.ts

@@ -0,0 +1,56 @@
+import { cva } from '../shared/index.ts'
+
+/**
+ * The outer scroll container — a dark monospaced surface that houses all
+ * terminal lines. Uses semantic card tokens so it inherits the active theme.
+ */
+export const terminalVariants = cva({
+  base: [
+    'relative rounded-lg border border-border bg-card font-mono text-sm',
+    'overflow-y-auto overflow-x-auto',
+    'p-4 space-y-0.5',
+  ].join(' '),
+  variants: {
+    maxHeight: {
+      sm: 'max-h-48',
+      md: 'max-h-80',
+      lg: 'max-h-[32rem]',
+      none: '',
+    },
+  },
+  defaultVariants: {
+    maxHeight: 'md',
+  },
+})
+
+/**
+ * A single terminal line. The `kind` variant maps each semantic category to
+ * the appropriate semantic token class — no raw color values inline.
+ */
+export const terminalLineVariants = cva({
+  base: 'block whitespace-pre-wrap break-all leading-relaxed',
+  variants: {
+    kind: {
+      /** The user-typed command: full foreground, bold weight. */
+      command: 'text-foreground font-semibold',
+      /** Normal program output. */
+      stdout: 'text-foreground',
+      /** Error / stderr output — uses the destructive semantic token. */
+      stderr: 'text-destructive',
+      /** Informational summary lines — muted, visually de-emphasised. */
+      info: 'text-muted-foreground',
+      /**
+       * Success / passing lines — green-family.
+       * Maps to `text-emerald-500` via the Tailwind semantic alias used
+       * across the design system; downstream themes can override this token.
+       */
+      success: 'text-emerald-500 dark:text-emerald-400',
+    },
+  },
+  defaultVariants: {
+    kind: 'stdout',
+  },
+})
+
+/** The prompt symbol (`$`, `❯`, …) preceding a command line. */
+export const terminalPromptClass = 'select-none mr-2 text-muted-foreground'

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'