@refraction-ui/astro 0.12.0 → 0.13.0

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'

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

@@ -0,0 +1,126 @@
+/** A node in the flow editor canvas. */
+export type FlowNode = {
+  id: string
+  x: number
+  y: number
+  width?: number
+  height?: number
+  label: string
+  selected?: boolean
+}
+
+/** A directed edge connecting two nodes. */
+export type FlowEdge = {
+  id: string
+  source: string
+  target: string
+  label?: string
+}
+
+/** Default node dimensions used when width/height are not specified. */
+const DEFAULT_NODE_WIDTH = 160
+const DEFAULT_NODE_HEIGHT = 48
+
+/**
+ * Compute the center point of a node in canvas coordinates.
+ * Uses the node's explicit dimensions when available, otherwise falls back to
+ * the default box size.
+ */
+export function nodeCenter(node: FlowNode): { x: number; y: number } {
+  const w = node.width ?? DEFAULT_NODE_WIDTH
+  const h = node.height ?? DEFAULT_NODE_HEIGHT
+  return { x: node.x + w / 2, y: node.y + h / 2 }
+}
+
+/**
+ * Find a node by id. Returns `undefined` when not found; callers must guard.
+ */
+export function nodeById(
+  nodes: FlowNode[],
+  id: string,
+): FlowNode | undefined {
+  return nodes.find((n) => n.id === id)
+}
+
+/**
+ * Produce an SVG cubic-bezier path `d` string between the anchor points of two
+ * nodes. The control handles extend horizontally from each anchor so the curve
+ * is smooth regardless of relative position — matching the easyloops
+ * architecture-editor style.
+ *
+ * Source anchor: right-center of the source node.
+ * Target anchor: left-center of the target node.
+ */
+export function edgePath(source: FlowNode, target: FlowNode): string {
+  const sw = source.width ?? DEFAULT_NODE_WIDTH
+  const sh = source.height ?? DEFAULT_NODE_HEIGHT
+  const th = target.height ?? DEFAULT_NODE_HEIGHT
+
+  const x1 = source.x + sw
+  const y1 = source.y + sh / 2
+  const x2 = target.x
+  const y2 = target.y + th / 2
+
+  const dx = Math.abs(x2 - x1)
+  const handleLen = Math.max(dx * 0.5, 40)
+
+  const cx1 = x1 + handleLen
+  const cy1 = y1
+  const cx2 = x2 - handleLen
+  const cy2 = y2
+
+  return `M ${x1} ${y1} C ${cx1} ${cy1}, ${cx2} ${cy2}, ${x2} ${y2}`
+}
+
+/**
+ * Compute the bounding box that contains all nodes. Useful for fitting the
+ * viewport to content. Returns zeros when the node list is empty.
+ */
+export function contentBounds(nodes: FlowNode[]): {
+  minX: number
+  minY: number
+  maxX: number
+  maxY: number
+} {
+  if (nodes.length === 0) {
+    return { minX: 0, minY: 0, maxX: 0, maxY: 0 }
+  }
+
+  let minX = Infinity
+  let minY = Infinity
+  let maxX = -Infinity
+  let maxY = -Infinity
+
+  for (const node of nodes) {
+    const w = node.width ?? DEFAULT_NODE_WIDTH
+    const h = node.height ?? DEFAULT_NODE_HEIGHT
+    if (node.x < minX) minX = node.x
+    if (node.y < minY) minY = node.y
+    if (node.x + w > maxX) maxX = node.x + w
+    if (node.y + h > maxY) maxY = node.y + h
+  }
+
+  return { minX, minY, maxX, maxY }
+}
+
+/** Accessibility and data attributes for the root flow editor container. */
+export interface FlowEditorAPI {
+  ariaProps: Record<string, string | number | boolean>
+  dataAttributes: Record<string, string>
+}
+
+/**
+ * Return the framework-agnostic root attributes for a FlowEditor.
+ * Adapters spread `ariaProps` and `dataAttributes` on the outermost element.
+ */
+export function createFlowEditor(): FlowEditorAPI {
+  return {
+    ariaProps: {
+      role: 'group',
+      'aria-label': 'Flow editor',
+    },
+    dataAttributes: {
+      'data-flow-editor': 'true',
+    },
+  }
+}

package/dist/flow-editor/index.ts

@@ -0,0 +1,18 @@
+export {
+  nodeCenter,
+  nodeById,
+  edgePath,
+  contentBounds,
+  createFlowEditor,
+  type FlowNode,
+  type FlowEdge,
+  type FlowEditorAPI,
+} from './flow-editor.js'
+
+export {
+  flowEditorVariants,
+  flowNodeVariants,
+  flowNodeLabelClass,
+  flowEdgePathClass,
+  flowEdgeLabelClass,
+} from './flow-editor.styles.js'

package/dist/graph-view/graph-view.styles.ts

@@ -0,0 +1,66 @@
+import { cva } from '../shared/index.ts'
+
+/** Outer wrapper for the graph canvas area. */
+export const graphViewVariants = cva({
+  base: 'relative w-full overflow-hidden rounded-lg border border-border bg-background',
+  variants: {},
+  defaultVariants: {},
+})
+
+/**
+ * Node chip: a positioned, clickable concept node colored by mastery state.
+ *
+ * `state` variant drives the visual treatment:
+ * - mastered      → filled primary (bg-primary / text-primary-foreground)
+ * - in-progress   → accent ring (ring-2 ring-ring bg-accent text-accent-foreground)
+ * - not-started   → muted (bg-muted text-muted-foreground)
+ * - highlight     → border-primary accent outline (border-primary bg-background text-foreground)
+ */
+export const graphNodeVariants = cva({
+  base: [
+    'absolute inline-flex items-center justify-center rounded-md border px-2 py-1',
+    'text-xs font-medium leading-none -translate-x-1/2 -translate-y-1/2',
+    'transition-colors focus-visible:outline-none focus-visible:ring-2',
+    'focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background',
+    'cursor-default select-none',
+  ].join(' '),
+  variants: {
+    state: {
+      mastered: 'border-transparent bg-primary text-primary-foreground',
+      'in-progress': 'border-transparent bg-accent text-accent-foreground ring-2 ring-ring',
+      'not-started': 'border-transparent bg-muted text-muted-foreground',
+      highlight: 'border-primary bg-background text-foreground',
+    },
+    interactive: {
+      true: 'cursor-pointer hover:opacity-90',
+      false: 'cursor-default',
+    },
+  },
+  defaultVariants: {
+    state: 'not-started',
+    interactive: 'false',
+  },
+})
+
+/** Label text rendered inside each node chip (already embedded in the chip). */
+export const graphNodeLabelClass = 'pointer-events-none whitespace-nowrap'
+
+/** SVG edge line/path classes. */
+export const graphEdgeClass =
+  'fill-none stroke-border stroke-[1.5] opacity-60'
+
+/** Legend chip: a small colored indicator + label for a single mastery state. */
+export const graphLegendChipVariants = cva({
+  base: 'inline-flex items-center gap-1.5 rounded-md border px-2 py-0.5 text-xs font-medium',
+  variants: {
+    state: {
+      mastered: 'border-transparent bg-primary text-primary-foreground',
+      'in-progress': 'border-transparent bg-accent text-accent-foreground ring-1 ring-ring',
+      'not-started': 'border-transparent bg-muted text-muted-foreground',
+      highlight: 'border-primary bg-background text-foreground',
+    },
+  },
+  defaultVariants: {
+    state: 'not-started',
+  },
+})