@refraction-ui/astro 0.12.0 → 0.14.0

package/dist/checklist/checklist.ts

@@ -0,0 +1,62 @@
+/** A single item in a checklist. */
+export interface ChecklistItemData {
+  /** Unique identifier for this item. */
+  id: string
+  /** Display label for the item. */
+  label: string
+  /** Whether the item is completed. */
+  checked?: boolean
+  /** Optional additional description text. */
+  description?: string
+}
+
+export interface ChecklistAPI {
+  /** ARIA attributes to spread on the list container (`role="list"`). */
+  ariaProps: { role: 'list' }
+  /** Data attributes for styling hooks. */
+  dataAttributes: Record<string, string>
+}
+
+/**
+ * Build the framework-agnostic container props for a checklist.
+ *
+ * Returns `role="list"` plus a `data-component` attribute. Adapters spread
+ * these onto their container element.
+ */
+export function createChecklist(): ChecklistAPI {
+  return {
+    ariaProps: { role: 'list' },
+    dataAttributes: { 'data-component': 'checklist' },
+  }
+}
+
+/**
+ * Compute progress statistics for a checklist.
+ *
+ * Pure function — does not mutate the array.
+ */
+export function checklistProgress(items: ChecklistItemData[]): {
+  completed: number
+  total: number
+  fraction: number
+} {
+  const total = items.length
+  const completed = items.filter((item) => item.checked).length
+  const fraction = total === 0 ? 0 : completed / total
+  return { completed, total, fraction }
+}
+
+/**
+ * Toggle a single item's `checked` state by id.
+ *
+ * Pure — returns a new array; the original is not mutated.
+ * Items whose id does not match are returned unchanged (same reference).
+ */
+export function toggleChecklistItem(
+  items: ChecklistItemData[],
+  id: string,
+): ChecklistItemData[] {
+  return items.map((item) =>
+    item.id === id ? { ...item, checked: !item.checked } : item,
+  )
+}

package/dist/checklist/index.ts

@@ -0,0 +1,18 @@
+export {
+  createChecklist,
+  checklistProgress,
+  toggleChecklistItem,
+  type ChecklistItemData,
+  type ChecklistAPI,
+} from './checklist.js'
+
+export {
+  checklistContainerClass,
+  checklistListClass,
+  checklistItemVariants,
+  checklistBoxVariants,
+  checklistLabelWrapClass,
+  checklistLabelVariants,
+  checklistDescriptionClass,
+  checklistProgressClass,
+} from './checklist.styles.js'

package/dist/editor-status-bar/editor-status-bar.styles.ts

@@ -0,0 +1,40 @@
+import { cva } from '../shared/index.ts'
+
+/**
+ * The outer bar — a thin, full-width strip that sits at the bottom of an IDE
+ * pane. Uses a monospace font stack so numeric values (line, col) don't shift
+ * width as they update.
+ */
+export const editorStatusBarVariants = cva({
+  base: [
+    'flex items-center justify-between',
+    'w-full h-6 px-2 gap-4',
+    'text-xs font-mono',
+    'bg-muted text-muted-foreground',
+    'border-t border-border',
+    'select-none',
+  ].join(' '),
+  variants: {},
+  defaultVariants: {},
+})
+
+/** The left or right group that holds a cluster of segments. */
+export const statusBarGroupClass = 'flex items-center gap-3 overflow-hidden'
+
+/**
+ * A single segment pill. The `tone` variant maps to semantic token classes so
+ * adapters never inline colour values.
+ */
+export const statusBarSegmentVariants = cva({
+  base: 'inline-flex items-center whitespace-nowrap truncate leading-none',
+  variants: {
+    tone: {
+      default: 'text-muted-foreground',
+      muted: 'text-muted-foreground/60',
+      accent: 'text-primary',
+    },
+  },
+  defaultVariants: {
+    tone: 'default',
+  },
+})

package/dist/editor-status-bar/editor-status-bar.ts

@@ -0,0 +1,78 @@
+import type { AccessibilityProps } from '../shared/index.ts'
+
+/** Horizontal alignment of a segment within the bar. */
+export type StatusSegmentAlign = 'left' | 'right'
+
+/** Visual tone / emphasis of a segment. */
+export type StatusSegmentTone = 'default' | 'muted' | 'accent'
+
+/** A single labelled item rendered in the status bar. */
+export interface StatusSegment {
+  /** Unique identifier for the segment. */
+  id: string
+  /** Text displayed in the segment. */
+  label: string
+  /** Which side of the bar this segment lives on. Defaults to `'left'`. */
+  align?: StatusSegmentAlign
+  /** Visual tone. Defaults to `'default'`. */
+  tone?: StatusSegmentTone
+}
+
+/** Return value of {@link createEditorStatusBar}. */
+export interface EditorStatusBarAPI {
+  /** ARIA attributes to spread on the bar element. */
+  ariaProps: Partial<AccessibilityProps>
+  /** Data attributes for styling hooks. */
+  dataAttributes: Record<string, string>
+}
+
+/**
+ * Format a cursor position as the canonical IDE string "Ln {line}, Col {col}".
+ *
+ * @example
+ * formatCursorPosition(17, 1) // → 'Ln 17, Col 1'
+ */
+export function formatCursorPosition(line: number, col: number): string {
+  return `Ln ${line}, Col ${col}`
+}
+
+/**
+ * Partition a flat list of segments into left- and right-aligned groups,
+ * preserving insertion order within each group.
+ */
+export function partitionSegments(segments: StatusSegment[]): {
+  left: StatusSegment[]
+  right: StatusSegment[]
+} {
+  const left: StatusSegment[] = []
+  const right: StatusSegment[] = []
+  for (const seg of segments) {
+    if (seg.align === 'right') {
+      right.push(seg)
+    } else {
+      left.push(seg)
+    }
+  }
+  return { left, right }
+}
+
+/**
+ * Build the framework-agnostic ARIA and data attributes for the status bar
+ * container.
+ *
+ * The bar uses `role="status"` with `aria-live="polite"` so screen readers
+ * announce updates (e.g. cursor position changes) without interrupting the
+ * user's current focus.
+ */
+export function createEditorStatusBar(): EditorStatusBarAPI {
+  const ariaProps: Partial<AccessibilityProps> = {
+    role: 'status',
+    'aria-live': 'polite',
+  }
+
+  const dataAttributes: Record<string, string> = {
+    'data-component': 'editor-status-bar',
+  }
+
+  return { ariaProps, dataAttributes }
+}

package/dist/editor-status-bar/index.ts

@@ -0,0 +1,15 @@
+export {
+  formatCursorPosition,
+  partitionSegments,
+  createEditorStatusBar,
+  type StatusSegmentAlign,
+  type StatusSegmentTone,
+  type StatusSegment,
+  type EditorStatusBarAPI,
+} from './editor-status-bar.js'
+
+export {
+  editorStatusBarVariants,
+  statusBarGroupClass,
+  statusBarSegmentVariants,
+} from './editor-status-bar.styles.js'

package/dist/editor-tabs/editor-tabs.styles.ts

@@ -0,0 +1,52 @@
+import { cva } from '../shared/index.ts'
+
+/** The tab bar container row. */
+export const editorTabsVariants = cva({
+  base: 'inline-flex items-end gap-0 border-b border-border bg-muted/40 overflow-x-auto',
+  variants: {},
+  defaultVariants: {},
+})
+
+/**
+ * A single tab button. The `state` variant switches between active and
+ * inactive treatments so adapters never inline these classes.
+ */
+export const editorTabVariants = cva({
+  base: [
+    'group inline-flex items-center gap-1.5 px-3 py-2 text-sm font-medium',
+    'border-b-2 transition-colors select-none whitespace-nowrap',
+    'focus-visible:outline-none focus-visible:ring-2',
+    'focus-visible:ring-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background',
+  ].join(' '),
+  variants: {
+    state: {
+      active: [
+        'border-primary text-foreground bg-background',
+        'border-t border-l border-r border-border border-b-background -mb-px',
+      ].join(' '),
+      inactive: [
+        'border-transparent text-muted-foreground',
+        'hover:text-foreground hover:bg-background/60',
+      ].join(' '),
+    },
+  },
+  defaultVariants: {
+    state: 'inactive',
+  },
+})
+
+/** The dot indicator shown when a tab has unsaved changes. */
+export const editorTabDirtyDotClass =
+  'size-1.5 rounded-full bg-amber-400 shrink-0'
+
+/** The close button inside a tab. */
+export const editorTabCloseButtonClass = [
+  'ml-1 inline-flex items-center justify-center rounded-sm size-4 shrink-0',
+  'text-muted-foreground opacity-0 transition-opacity',
+  'group-hover:opacity-100 focus-visible:opacity-100',
+  'hover:bg-accent hover:text-foreground',
+  'focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring',
+].join(' ')
+
+/** The optional icon slot to the left of the label. */
+export const editorTabIconClass = 'shrink-0 text-[0.85em] leading-none'

package/dist/editor-tabs/editor-tabs.ts

@@ -0,0 +1,82 @@
+import type { AccessibilityProps } from '../shared/index.ts'
+
+/** A single tab entry in the editor tab bar. */
+export interface EditorTabData {
+  /** Unique identifier for the tab. */
+  id: string
+  /** Display label (e.g. "solution.py"). */
+  label: string
+  /** Optional icon — a short string like an emoji or a ligature glyph. */
+  icon?: string
+  /** Whether the tab has unsaved changes (shows a dirty dot). */
+  dirty?: boolean
+  /** Whether the tab shows a close button. */
+  closable?: boolean
+}
+
+export interface EditorTabsProps {
+  /** The id of the currently active tab. */
+  activeId?: string
+}
+
+export interface EditorTabsAPI {
+  /** ARIA attributes to spread on the tab list container. */
+  ariaProps: Partial<AccessibilityProps>
+  /** Data attributes for styling hooks. */
+  dataAttributes: Record<string, string>
+}
+
+/**
+ * Build the framework-agnostic container props for an IDE-style editor tab bar.
+ *
+ * Returns `role="tablist"` plus data attributes. Each individual tab is
+ * `role="tab"` with `aria-selected`; adapters spread ariaProps on the container
+ * and render the tabs themselves.
+ */
+export function createEditorTabs(props: EditorTabsProps = {}): EditorTabsAPI {
+  const { activeId } = props
+
+  const ariaProps: Partial<AccessibilityProps> = {
+    role: 'tablist',
+  }
+
+  const dataAttributes: Record<string, string> = {}
+  if (activeId !== undefined) {
+    dataAttributes['data-active-id'] = activeId
+  }
+
+  return { ariaProps, dataAttributes }
+}
+
+/**
+ * Roving keyboard navigation for the editor tab bar.
+ *
+ * Unlike a rating scale, tabs **wrap** at the ends so you can cycle through
+ * them continuously — matching standard tab-bar behaviour (similar to
+ * segmented-control). Home/End jump to the first/last tab.
+ *
+ * - ArrowRight → next (wraps to first after last)
+ * - ArrowLeft  → previous (wraps to last before first)
+ * - Home       → first
+ * - End        → last
+ */
+export function getNextTabIndex(
+  currentIndex: number,
+  key: string,
+  count: number,
+): number {
+  if (count <= 0) return currentIndex
+
+  switch (key) {
+    case 'ArrowRight':
+      return (currentIndex + 1) % count
+    case 'ArrowLeft':
+      return (currentIndex - 1 + count) % count
+    case 'Home':
+      return 0
+    case 'End':
+      return count - 1
+    default:
+      return currentIndex
+  }
+}

package/dist/editor-tabs/index.ts

@@ -0,0 +1,15 @@
+export {
+  createEditorTabs,
+  getNextTabIndex,
+  type EditorTabData,
+  type EditorTabsProps,
+  type EditorTabsAPI,
+} from './editor-tabs.js'
+
+export {
+  editorTabsVariants,
+  editorTabVariants,
+  editorTabDirtyDotClass,
+  editorTabCloseButtonClass,
+  editorTabIconClass,
+} from './editor-tabs.styles.js'

package/dist/floating-reactions/floating-reactions.styles.ts

@@ -0,0 +1,54 @@
+import { cva } from '../shared/index.ts'
+
+/**
+ * Overlay container — fills the parent with absolute positioning so reactions
+ * float over content. pointer-events-none keeps the overlay non-interactive;
+ * overflow-hidden clips reactions that drift outside the bounds.
+ */
+export const floatingReactionsVariants = cva({
+  base: 'absolute inset-0 pointer-events-none overflow-hidden',
+  variants: {
+    /**
+     * Whether the overlay is currently active (has reactions). The parent may
+     * toggle visibility, but we keep the node mounted to preserve live-region
+     * semantics.
+     */
+    active: {
+      true: '',
+      false: '',
+    },
+  },
+  defaultVariants: {
+    active: 'false',
+  },
+})
+
+/**
+ * A single floating reaction item.
+ *
+ * The float-up animation is driven by the class
+ * `animate-[float-up_3s_ease-out_forwards]`. Consumers must supply the
+ * `@keyframes float-up` rule in their global CSS or Tailwind config:
+ *
+ * ```css
+ * @keyframes float-up {
+ *   0%   { transform: translateY(0);    opacity: 1; }
+ *   80%  { opacity: 1; }
+ *   100% { transform: translateY(-80%); opacity: 0; }
+ * }
+ * ```
+ *
+ * Without the keyframe the item will still render in place and fade on removal
+ * (graceful degradation).
+ */
+export const floatingReactionItemClass = [
+  'absolute bottom-4',
+  'text-3xl leading-none select-none',
+  'animate-[float-up_3s_ease-out_forwards]',
+].join(' ')
+
+/**
+ * Accessible label node for the reaction — visually hidden so screen readers
+ * read the emoji description once and don't repeat the decorative glyph.
+ */
+export const floatingReactionLabelClass = 'sr-only'

package/dist/floating-reactions/floating-reactions.ts

@@ -0,0 +1,85 @@
+/**
+ * Headless core for floating emoji reactions.
+ *
+ * An emoji burst overlay where reactions animate upward and fade — distinct
+ * from the static reaction-bar (which shows counts). This module is JSX-free
+ * and framework-agnostic; adapters consume it and manage timing with
+ * REACTION_LIFETIME_MS.
+ */
+
+/** A single transient reaction displayed in the overlay. */
+export interface FloatingReaction {
+  /** Stable unique id assigned by the adapter (used as React key / tracker). */
+  id: string
+  /** The emoji character(s) to display, e.g. '👋' or '❤️'. */
+  emoji: string
+  /**
+   * Horizontal offset bucket (0-indexed). Adapters use laneOffsetPercent() to
+   * convert this into a CSS left % so multiple reactions spread across the
+   * overlay rather than stacking.
+   */
+  lane?: number
+}
+
+/**
+ * How long (ms) a floating reaction should live before the adapter removes it.
+ * Use this constant in adapters to drive setTimeout-based auto-expiry so the
+ * value stays in sync with the CSS animation duration.
+ */
+export const REACTION_LIFETIME_MS = 3000
+
+/**
+ * Compute the horizontal left-offset percentage for a given lane bucket.
+ *
+ * Pure and deterministic — safe to call in tests and SSR.
+ *
+ * @param lane  Zero-indexed lane number (clamped to [0, lanes-1]).
+ * @param lanes Total number of lanes (default 5).
+ * @returns A percentage value in [0, 100].
+ *
+ * @example
+ * laneOffsetPercent(0, 5) // 10
+ * laneOffsetPercent(2, 5) // 50
+ * laneOffsetPercent(4, 5) // 90
+ */
+export function laneOffsetPercent(lane = 0, lanes = 5): number {
+  if (lanes <= 0) return 50
+  const clamped = Math.max(0, Math.min(lane, lanes - 1))
+  // Divide [0,100] into `lanes` equal buckets and return the centre of each.
+  const step = 100 / lanes
+  return step * clamped + step / 2
+}
+
+export interface FloatingReactionsAriaProps {
+  role: string
+  'aria-live': 'polite' | 'assertive' | 'off'
+  'aria-label': string
+}
+
+export interface FloatingReactionsAPI {
+  /** ARIA attributes to spread on the overlay container. */
+  ariaProps: FloatingReactionsAriaProps
+  /** Data attributes for styling hooks. */
+  dataAttributes: Record<string, string>
+}
+
+/**
+ * Build the framework-agnostic accessibility and data props for the overlay
+ * container.
+ *
+ * The overlay is a `role="status"` live region so screen readers announce
+ * incoming reactions without interrupting the user (polite).
+ */
+export function createFloatingReactions(): FloatingReactionsAPI {
+  const ariaProps: FloatingReactionsAriaProps = {
+    role: 'status',
+    'aria-live': 'polite',
+    'aria-label': 'Reactions',
+  }
+
+  const dataAttributes: Record<string, string> = {
+    'data-component': 'floating-reactions',
+  }
+
+  return { ariaProps, dataAttributes }
+}

package/dist/floating-reactions/index.ts

@@ -0,0 +1,14 @@
+export {
+  createFloatingReactions,
+  laneOffsetPercent,
+  REACTION_LIFETIME_MS,
+  type FloatingReaction,
+  type FloatingReactionsAriaProps,
+  type FloatingReactionsAPI,
+} from './floating-reactions.js'
+
+export {
+  floatingReactionsVariants,
+  floatingReactionItemClass,
+  floatingReactionLabelClass,
+} from './floating-reactions.styles.js'

package/dist/flow-editor/flow-editor.styles.ts

@@ -0,0 +1,56 @@
+import { cva } from '../shared/index.ts'
+
+/**
+ * Root wrapper for the flow editor canvas. Sized to fill its container and
+ * provides a relative positioning context for the node/edge layers.
+ */
+export const flowEditorVariants = cva({
+  base: 'relative w-full overflow-hidden bg-background border border-border rounded-lg',
+  variants: {
+    size: {
+      sm: 'h-64',
+      md: 'h-96',
+      lg: 'h-[32rem]',
+    },
+  },
+  defaultVariants: {
+    size: 'md',
+  },
+})
+
+/**
+ * A single node box. The `selected` variant adds a ring to signal the active
+ * selection; semantic token classes are used throughout so theming works
+ * without overrides.
+ */
+export const flowNodeVariants = cva({
+  base: [
+    'absolute flex items-center justify-center rounded-md border',
+    'bg-card border-border text-card-foreground text-sm font-medium',
+    'cursor-pointer select-none transition-shadow',
+    'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background',
+  ].join(' '),
+  variants: {
+    selected: {
+      true: 'ring-2 ring-ring ring-primary shadow-md',
+      false: 'hover:border-primary/50 hover:shadow-sm',
+    },
+  },
+  defaultVariants: {
+    selected: 'false',
+  },
+})
+
+/** Accessible label text inside a node box. */
+export const flowNodeLabelClass = 'px-3 py-2 truncate pointer-events-none'
+
+/**
+ * SVG `<path>` element class for an edge. `currentColor` is used so the
+ * stroke inherits from `text-muted-foreground` set on the SVG container.
+ */
+export const flowEdgePathClass =
+  'fill-none stroke-current stroke-2 transition-opacity'
+
+/** Text label positioned at the midpoint of an edge. */
+export const flowEdgeLabelClass =
+  'text-xs fill-muted-foreground select-none pointer-events-none'