@refraction-ui/react 0.13.0 → 0.14.0

package/dist/internal/audio-room/index.d.ts

@@ -0,0 +1,91 @@
+/** A participant in an audio-only room. */
+interface AudioParticipant {
+    /** Unique participant identifier. */
+    id: string;
+    /** Display name shown below the orb. */
+    name: string;
+    /** Optional avatar image URL. Falls back to initials when absent. */
+    avatarUrl?: string;
+    /** Whether this participant is currently speaking. */
+    speaking?: boolean;
+    /** Whether this participant's microphone is muted. */
+    muted?: boolean;
+    /** Whether this participant has raised their hand. */
+    handRaised?: boolean;
+}
+interface AudioRoomAPI {
+    /** ARIA attributes to spread on the room container element. */
+    ariaProps: {
+        role: 'group';
+    };
+    /** Data attributes for styling hooks. */
+    dataAttributes: Record<string, string>;
+}
+/**
+ * Derive up to two uppercase initials from a display name.
+ *
+ * Examples: "Alice" → "A", "Bob Smith" → "BS", "Dr. Jane Doe" → "JD"
+ * (only word-initial alphabetic characters are used).
+ */
+declare function getInitials(name: string): string;
+/**
+ * Determine the number of grid columns for the orb grid.
+ *
+ * | Count  | Columns |
+ * |--------|---------|
+ * | 1      | 1       |
+ * | 2–4    | 2       |
+ * | 5–9    | 3       |
+ * | 10+    | 4       |
+ */
+declare function orbColumns(count: number): number;
+/**
+ * Build the framework-agnostic container props for an audio room.
+ *
+ * Returns `role="group"` plus data attributes that adapters spread onto
+ * their outermost container element.
+ */
+declare function createAudioRoom(): AudioRoomAPI;
+
+/**
+ * Grid container that lays out the speaking orbs.
+ *
+ * Column count and gap are applied via inline `gridTemplateColumns` in
+ * adapters (dynamic count); this cva handles only the non-dynamic layout
+ * concerns — display, alignment, and padding.
+ */
+declare const audioRoomVariants: (props?: ({} & {
+    className?: string;
+}) | undefined) => string;
+/**
+ * Wrapper cell for a single orb + name label combination.
+ * Keeps the avatar and label centred as a column.
+ */
+declare const audioRoomOrbCellVariants: (props?: ({} & {
+    className?: string;
+}) | undefined) => string;
+/**
+ * The circular avatar / speaking indicator.
+ *
+ * - `speaking` adds an animated ring using the primary colour.
+ * - `muted` dims the orb slightly to signal a silenced microphone.
+ */
+declare const speakingOrbVariants: (props?: ({
+    speaking?: "true" | "false" | undefined;
+    muted?: "true" | "false" | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+/** Name label rendered below each orb. */
+declare const audioRoomNameLabelClass = "text-sm font-medium text-foreground text-center max-w-[6rem] truncate";
+/**
+ * Muted badge — a small indicator overlaid at the bottom-right of the orb
+ * to show the microphone is off.
+ */
+declare const audioRoomMutedBadgeClass: string;
+/**
+ * Hand-raise badge — shown at the top-right of the orb.
+ */
+declare const audioRoomHandBadgeClass: string;
+
+export { type AudioParticipant, type AudioRoomAPI, audioRoomHandBadgeClass, audioRoomMutedBadgeClass, audioRoomNameLabelClass, audioRoomOrbCellVariants, audioRoomVariants, createAudioRoom, getInitials, orbColumns, speakingOrbVariants };

package/dist/internal/call-controls/index.d.ts

@@ -0,0 +1,83 @@
+import { AccessibilityProps } from '../shared/index.js';
+
+/** Visual/semantic tone of a call control button. */
+type CallControlTone = 'default' | 'active' | 'destructive';
+/**
+ * Toggleable state for controls like mic or camera.
+ * `'on'`  = currently active (mic/camera live).
+ * `'off'` = currently muted/disabled.
+ */
+type CallControlState = 'on' | 'off';
+/**
+ * A single control descriptor used by adapters to drive button rendering.
+ */
+interface CallControlItem {
+    /** Unique identifier for this control. */
+    id: string;
+    /** Visible label (also used as aria-label). */
+    label: string;
+    /** Optional icon to render inside the button. */
+    icon?: string;
+    /** Explicit tone override; when omitted `controlTone` is used with `state`. */
+    tone?: CallControlTone;
+    /** Toggleable state (present only for toggleable controls). */
+    pressed?: boolean;
+}
+interface CallControlsProps {
+    /** Controls to render. */
+    controls?: CallControlItem[];
+}
+interface CallControlsAPI {
+    /** ARIA attributes to spread on the toolbar element (`role="toolbar"`). */
+    ariaProps: Partial<AccessibilityProps>;
+    /** Data attributes for styling hooks. */
+    dataAttributes: Record<string, string>;
+}
+/**
+ * Derive the visual tone for a control given its kind and current toggle state.
+ *
+ * Convention used by easyloops meeting toolbar:
+ * - `leave` / `end`  → always `'destructive'`
+ * - any control that is `'off'` (muted/stopped) → `'destructive'` to signal
+ *   the user that something is disabled (e.g. mic muted = red indicator).
+ * - a control that is `'on'` → `'active'` (lit up / highlighted).
+ * - otherwise → `'default'` (neutral).
+ */
+declare function controlTone(kind: string, state: CallControlState | undefined): CallControlTone;
+/**
+ * Build the framework-agnostic toolbar props for a call-controls bar.
+ *
+ * Returns `role="toolbar"` plus `aria-label="Call controls"` and data
+ * attributes; adapters spread these onto their container element.
+ */
+declare function createCallControls(_props?: CallControlsProps): CallControlsAPI;
+
+/**
+ * Toolbar container — flex row, centred, with a card background and gap
+ * between the control buttons.
+ */
+declare const callControlsVariants: (props?: ({
+    size?: "sm" | "md" | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+/**
+ * Individual call-control button.
+ *
+ * `tone` variants:
+ * - `default`     → neutral muted appearance (standard inactive controls)
+ * - `active`      → primary/highlighted (e.g. mic on, screen-share running)
+ * - `destructive` → red/danger (leave button or a muted mic indicator)
+ *
+ * `size` variants match the toolbar container.
+ */
+declare const callControlButtonVariants: (props?: ({
+    size?: "sm" | "md" | undefined;
+    tone?: "default" | "active" | "destructive" | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+/** Label beneath the icon inside a call-control button. */
+declare const callControlLabelClass = "sr-only text-[10px] leading-none mt-0.5";
+
+export { type CallControlItem, type CallControlState, type CallControlTone, type CallControlsAPI, type CallControlsProps, callControlButtonVariants, callControlLabelClass, callControlsVariants, controlTone, createCallControls };

package/dist/internal/checklist/index.d.ts

@@ -0,0 +1,84 @@
+/** A single item in a checklist. */
+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;
+}
+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.
+ */
+declare function createChecklist(): ChecklistAPI;
+/**
+ * Compute progress statistics for a checklist.
+ *
+ * Pure function — does not mutate the array.
+ */
+declare function checklistProgress(items: ChecklistItemData[]): {
+    completed: number;
+    total: number;
+    fraction: number;
+};
+/**
+ * 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).
+ */
+declare function toggleChecklistItem(items: ChecklistItemData[], id: string): ChecklistItemData[];
+
+/** Outer container that wraps the list and optional progress summary. */
+declare const checklistContainerClass = "flex flex-col gap-2";
+/** The `role="list"` element holding all item rows. */
+declare const checklistListClass = "flex flex-col gap-1";
+/**
+ * A single item row — a button with checkbox semantics.
+ *
+ * The `checked` variant applies muted text and a line-through on the label
+ * to communicate completion without relying solely on the checkbox visual.
+ */
+declare const checklistItemVariants: (props?: ({
+    checked?: "true" | "false" | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+/**
+ * The visual checkbox box (the square indicator beside the label).
+ *
+ * The `checked` variant fills the box with the primary colour and shows a
+ * checkmark via a border trick; the unchecked state shows an empty border.
+ */
+declare const checklistBoxVariants: (props?: ({
+    checked?: "true" | "false" | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+/** Wrapper for label + optional description text. */
+declare const checklistLabelWrapClass = "flex flex-col gap-0.5 min-w-0";
+/** The item's primary label. Strikethrough is applied when the item is checked. */
+declare const checklistLabelVariants: (props?: ({
+    checked?: "true" | "false" | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+/** Optional description — always in muted text, smaller than the label. */
+declare const checklistDescriptionClass = "text-xs text-muted-foreground";
+/** Progress summary line shown below the list when `showProgress` is true. */
+declare const checklistProgressClass = "text-xs text-muted-foreground tabular-nums";
+
+export { type ChecklistAPI, type ChecklistItemData, checklistBoxVariants, checklistContainerClass, checklistDescriptionClass, checklistItemVariants, checklistLabelVariants, checklistLabelWrapClass, checklistListClass, checklistProgress, checklistProgressClass, createChecklist, toggleChecklistItem };

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

@@ -0,0 +1,70 @@
+import { AccessibilityProps } from '../shared/index.js';
+
+/** Horizontal alignment of a segment within the bar. */
+type StatusSegmentAlign = 'left' | 'right';
+/** Visual tone / emphasis of a segment. */
+type StatusSegmentTone = 'default' | 'muted' | 'accent';
+/** A single labelled item rendered in the status bar. */
+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}. */
+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'
+ */
+declare function formatCursorPosition(line: number, col: number): string;
+/**
+ * Partition a flat list of segments into left- and right-aligned groups,
+ * preserving insertion order within each group.
+ */
+declare function partitionSegments(segments: StatusSegment[]): {
+    left: StatusSegment[];
+    right: StatusSegment[];
+};
+/**
+ * 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.
+ */
+declare function createEditorStatusBar(): EditorStatusBarAPI;
+
+/**
+ * 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.
+ */
+declare const editorStatusBarVariants: (props?: ({} & {
+    className?: string;
+}) | undefined) => string;
+/** The left or right group that holds a cluster of segments. */
+declare 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.
+ */
+declare const statusBarSegmentVariants: (props?: ({
+    tone?: "default" | "muted" | "accent" | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+
+export { type EditorStatusBarAPI, type StatusSegment, type StatusSegmentAlign, type StatusSegmentTone, createEditorStatusBar, editorStatusBarVariants, formatCursorPosition, partitionSegments, statusBarGroupClass, statusBarSegmentVariants };

package/dist/internal/editor-tabs/index.d.ts

@@ -0,0 +1,68 @@
+import { AccessibilityProps } from '../shared/index.js';
+
+/** A single tab entry in the editor tab bar. */
+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;
+}
+interface EditorTabsProps {
+    /** The id of the currently active tab. */
+    activeId?: string;
+}
+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.
+ */
+declare function createEditorTabs(props?: EditorTabsProps): EditorTabsAPI;
+/**
+ * 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
+ */
+declare function getNextTabIndex(currentIndex: number, key: string, count: number): number;
+
+/** The tab bar container row. */
+declare const editorTabsVariants: (props?: ({} & {
+    className?: string;
+}) | undefined) => string;
+/**
+ * A single tab button. The `state` variant switches between active and
+ * inactive treatments so adapters never inline these classes.
+ */
+declare const editorTabVariants: (props?: ({
+    state?: "active" | "inactive" | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+/** The dot indicator shown when a tab has unsaved changes. */
+declare const editorTabDirtyDotClass = "size-1.5 rounded-full bg-amber-400 shrink-0";
+/** The close button inside a tab. */
+declare const editorTabCloseButtonClass: string;
+/** The optional icon slot to the left of the label. */
+declare const editorTabIconClass = "shrink-0 text-[0.85em] leading-none";
+
+export { type EditorTabData, type EditorTabsAPI, type EditorTabsProps, createEditorTabs, editorTabCloseButtonClass, editorTabDirtyDotClass, editorTabIconClass, editorTabVariants, editorTabsVariants, getNextTabIndex };

package/dist/internal/floating-reactions/index.d.ts

@@ -0,0 +1,98 @@
+/**
+ * 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. */
+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.
+ */
+declare 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
+ */
+declare function laneOffsetPercent(lane?: number, lanes?: number): number;
+interface FloatingReactionsAriaProps {
+    role: string;
+    'aria-live': 'polite' | 'assertive' | 'off';
+    'aria-label': string;
+}
+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).
+ */
+declare function createFloatingReactions(): FloatingReactionsAPI;
+
+/**
+ * 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.
+ */
+declare const floatingReactionsVariants: (props?: ({
+    active?: "true" | "false" | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+/**
+ * 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).
+ */
+declare const floatingReactionItemClass: string;
+/**
+ * Accessible label node for the reaction — visually hidden so screen readers
+ * read the emoji description once and don't repeat the decorative glyph.
+ */
+declare const floatingReactionLabelClass = "sr-only";
+
+export { type FloatingReaction, type FloatingReactionsAPI, type FloatingReactionsAriaProps, REACTION_LIFETIME_MS, createFloatingReactions, floatingReactionItemClass, floatingReactionLabelClass, floatingReactionsVariants, laneOffsetPercent };

package/dist/internal/flow-editor/index.d.ts

@@ -0,0 +1,91 @@
+/** A node in the flow editor canvas. */
+type FlowNode = {
+    id: string;
+    x: number;
+    y: number;
+    width?: number;
+    height?: number;
+    label: string;
+    selected?: boolean;
+};
+/** A directed edge connecting two nodes. */
+type FlowEdge = {
+    id: string;
+    source: string;
+    target: string;
+    label?: string;
+};
+/**
+ * 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.
+ */
+declare function nodeCenter(node: FlowNode): {
+    x: number;
+    y: number;
+};
+/**
+ * Find a node by id. Returns `undefined` when not found; callers must guard.
+ */
+declare function nodeById(nodes: FlowNode[], id: string): FlowNode | undefined;
+/**
+ * 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.
+ */
+declare function edgePath(source: FlowNode, target: FlowNode): string;
+/**
+ * Compute the bounding box that contains all nodes. Useful for fitting the
+ * viewport to content. Returns zeros when the node list is empty.
+ */
+declare function contentBounds(nodes: FlowNode[]): {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+};
+/** Accessibility and data attributes for the root flow editor container. */
+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.
+ */
+declare function createFlowEditor(): FlowEditorAPI;
+
+/**
+ * Root wrapper for the flow editor canvas. Sized to fill its container and
+ * provides a relative positioning context for the node/edge layers.
+ */
+declare const flowEditorVariants: (props?: ({
+    size?: "sm" | "md" | "lg" | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+/**
+ * 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.
+ */
+declare const flowNodeVariants: (props?: ({
+    selected?: "true" | "false" | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+/** Accessible label text inside a node box. */
+declare 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.
+ */
+declare const flowEdgePathClass = "fill-none stroke-current stroke-2 transition-opacity";
+/** Text label positioned at the midpoint of an edge. */
+declare const flowEdgeLabelClass = "text-xs fill-muted-foreground select-none pointer-events-none";
+
+export { type FlowEdge, type FlowEditorAPI, type FlowNode, contentBounds, createFlowEditor, edgePath, flowEdgeLabelClass, flowEdgePathClass, flowEditorVariants, flowNodeLabelClass, flowNodeVariants, nodeById, nodeCenter };