@refraction-ui/astro 0.12.0 → 0.14.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/section-head/index.ts

@@ -0,0 +1,13 @@
+export {
+  createSectionHead,
+  type SectionHeadAlign,
+  type SectionHeadProps,
+  type SectionHeadAPI,
+} from './section-head.js'
+
+export {
+  sectionHeadVariants,
+  sectionHeadKickerClass,
+  sectionHeadTitleClass,
+  sectionHeadLedeClass,
+} from './section-head.styles.js'

package/dist/section-head/section-head.styles.ts

@@ -0,0 +1,30 @@
+import { cva } from '../shared/index.ts'
+
+/**
+ * Container variant that controls the alignment of the whole cluster.
+ * Center: auto-margins + text-center + constrained max-width for comfortable
+ * line length. Left: no margin constraint, flush left.
+ */
+export const sectionHeadVariants = cva({
+  base: 'flex flex-col',
+  variants: {
+    align: {
+      center: 'mx-auto text-center max-w-2xl',
+      left: 'text-left',
+    },
+  },
+  defaultVariants: {
+    align: 'center',
+  },
+})
+
+/** Small-caps eyebrow label above the title. */
+export const sectionHeadKickerClass =
+  'text-[11px] uppercase tracking-widest text-primary font-semibold'
+
+/** Primary h2 heading. */
+export const sectionHeadTitleClass =
+  'text-3xl sm:text-4xl font-bold tracking-tight text-foreground'
+
+/** Optional lede paragraph below the title. */
+export const sectionHeadLedeClass = 'mt-3 text-muted-foreground leading-relaxed'

package/dist/section-head/section-head.ts

@@ -0,0 +1,28 @@
+/** Horizontal alignment of the section head cluster. */
+export type SectionHeadAlign = 'center' | 'left'
+
+export interface SectionHeadProps {
+  /** Alignment of the kicker, title, and lede. */
+  align?: SectionHeadAlign
+}
+
+export interface SectionHeadAPI {
+  /** Data attributes for styling hooks. */
+  dataAttributes: Record<string, string>
+}
+
+/**
+ * Build the framework-agnostic data attributes for a SectionHead.
+ *
+ * Returns data-align so adapters can apply styles via CSS or Tailwind
+ * variants. All visual logic (classes, cva) lives in `section-head.styles.ts`.
+ */
+export function createSectionHead(props: SectionHeadProps = {}): SectionHeadAPI {
+  const { align = 'center' } = props
+
+  const dataAttributes: Record<string, string> = {
+    'data-align': align,
+  }
+
+  return { dataAttributes }
+}

package/dist/stat-grid/index.ts

@@ -0,0 +1,13 @@
+export {
+  createStatGrid,
+  statColumns,
+  type StatItem,
+  type StatGridAPI,
+} from './stat-grid.js'
+
+export {
+  statGridVariants,
+  statItemClass,
+  statValueClass,
+  statLabelClass,
+} from './stat-grid.styles.js'

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

@@ -0,0 +1,25 @@
+import { cva } from '../shared/index.ts'
+
+/** Grid container that lays out stat items. */
+export const statGridVariants = cva({
+  base: 'grid gap-8',
+  variants: {
+    columns: {
+      '1': 'grid-cols-1',
+      '2': 'grid-cols-2',
+      '3': 'grid-cols-3',
+    },
+  },
+  defaultVariants: {
+    columns: '3',
+  },
+})
+
+/** Individual stat item container (role="listitem"). */
+export const statItemClass = 'flex flex-col'
+
+/** The large bold value of the stat. */
+export const statValueClass = 'text-xl sm:text-2xl font-bold text-primary'
+
+/** The descriptive label below the value. */
+export const statLabelClass = 'mt-1 text-sm text-muted-foreground leading-snug'

package/dist/stat-grid/stat-grid.ts

@@ -0,0 +1,41 @@
+/** A single stat callout displayed in the grid. */
+export type StatItem = {
+  /** The primary value displayed prominently (e.g. "10k+", "$4.2M"). */
+  value: string
+  /** The descriptive label shown below the value. */
+  label: string
+}
+
+export interface StatGridAPI {
+  /** ARIA attributes to spread on the grid container element (`role="list"`). */
+  ariaProps: { role: 'list' }
+  /** Data attributes for styling hooks. */
+  dataAttributes: Record<string, string>
+}
+
+/**
+ * Compute the number of grid columns for a stat grid.
+ *
+ * - 1 item  → 1 column
+ * - 2 items → 2 columns
+ * - 3 or more items → capped at `max` (default 3)
+ */
+export function statColumns(count: number, max = 3): number {
+  if (count <= 0) return 1
+  if (count === 1) return 1
+  if (count === 2) return 2
+  return Math.min(count, max)
+}
+
+/**
+ * Build the framework-agnostic container props for a stat grid.
+ *
+ * Returns `role="list"` and data attributes; adapters spread these onto their
+ * container element and render the items themselves.
+ */
+export function createStatGrid(): StatGridAPI {
+  return {
+    ariaProps: { role: 'list' },
+    dataAttributes: {},
+  }
+}

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'