@refraction-ui/react 0.4.1 → 0.5.0

package/dist/internal/slide-viewer/index.d.cts

@@ -0,0 +1,72 @@
+import { KeyboardHandlerMap, AccessibilityProps, TokenContract } from '../shared/index.cjs';
+
+type SlideType = 'lesson' | 'quiz' | 'exercise' | 'intro' | 'summary';
+type BookmarkType = 'important' | 'difficult' | 'to-revise';
+interface SlideData {
+    id: string;
+    type: SlideType;
+    content: string;
+}
+interface SlideViewerProps {
+    slides: SlideData[];
+    initialSlide?: number;
+    onSlideChange?: (index: number) => void;
+    onComplete?: () => void;
+}
+interface SlideViewerState {
+    currentSlide: number;
+    totalSlides: number;
+    bookmarks: Map<number, BookmarkType>;
+}
+interface SlideViewerAPI {
+    /** Current viewer state */
+    state: SlideViewerState;
+    /** Navigate to the next slide */
+    next: () => void;
+    /** Navigate to the previous slide */
+    prev: () => void;
+    /** Navigate to a specific slide index */
+    goTo: (index: number) => void;
+    /** Toggle a bookmark on the current slide */
+    toggleBookmark: (type: BookmarkType) => void;
+    /** Get all bookmarks as an array of entries */
+    getBookmarks: () => Array<{
+        slide: number;
+        type: BookmarkType;
+    }>;
+    /** Current progress as a number between 0 and 1 */
+    progress: number;
+    /** Keyboard handlers for slide navigation */
+    keyboardHandlers: KeyboardHandlerMap;
+    /** ARIA props for the current slide */
+    getSlideAriaProps: () => Partial<AccessibilityProps> & {
+        'aria-roledescription'?: string;
+    };
+}
+/**
+ * Create a headless slide viewer.
+ *
+ * Manages slide navigation state, bookmarks, progress tracking,
+ * and keyboard navigation. Framework wrappers handle rendering.
+ */
+declare function createSlideViewer(props: SlideViewerProps): SlideViewerAPI;
+
+declare const slideViewerTokens: TokenContract;
+declare const slideViewerVariants: (props?: ({
+    size?: "compact" | "default" | "full" | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+declare const slideViewerProgressBarVariants: (props?: ({
+    position?: "top" | "bottom" | "inline" | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+
+declare const slideTypeBadgeVariants: (props?: ({
+    type?: "lesson" | "quiz" | "exercise" | "intro" | "summary" | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+
+export { type BookmarkType, type SlideData, type SlideType, type SlideViewerAPI, type SlideViewerProps, type SlideViewerState, createSlideViewer, slideViewerProgressBarVariants as progressBarVariants, slideTypeBadgeVariants, slideViewerTokens, slideViewerVariants };

package/dist/internal/slide-viewer/index.d.ts

@@ -0,0 +1,72 @@
+import { KeyboardHandlerMap, AccessibilityProps, TokenContract } from '../shared/index.js';
+
+type SlideType = 'lesson' | 'quiz' | 'exercise' | 'intro' | 'summary';
+type BookmarkType = 'important' | 'difficult' | 'to-revise';
+interface SlideData {
+    id: string;
+    type: SlideType;
+    content: string;
+}
+interface SlideViewerProps {
+    slides: SlideData[];
+    initialSlide?: number;
+    onSlideChange?: (index: number) => void;
+    onComplete?: () => void;
+}
+interface SlideViewerState {
+    currentSlide: number;
+    totalSlides: number;
+    bookmarks: Map<number, BookmarkType>;
+}
+interface SlideViewerAPI {
+    /** Current viewer state */
+    state: SlideViewerState;
+    /** Navigate to the next slide */
+    next: () => void;
+    /** Navigate to the previous slide */
+    prev: () => void;
+    /** Navigate to a specific slide index */
+    goTo: (index: number) => void;
+    /** Toggle a bookmark on the current slide */
+    toggleBookmark: (type: BookmarkType) => void;
+    /** Get all bookmarks as an array of entries */
+    getBookmarks: () => Array<{
+        slide: number;
+        type: BookmarkType;
+    }>;
+    /** Current progress as a number between 0 and 1 */
+    progress: number;
+    /** Keyboard handlers for slide navigation */
+    keyboardHandlers: KeyboardHandlerMap;
+    /** ARIA props for the current slide */
+    getSlideAriaProps: () => Partial<AccessibilityProps> & {
+        'aria-roledescription'?: string;
+    };
+}
+/**
+ * Create a headless slide viewer.
+ *
+ * Manages slide navigation state, bookmarks, progress tracking,
+ * and keyboard navigation. Framework wrappers handle rendering.
+ */
+declare function createSlideViewer(props: SlideViewerProps): SlideViewerAPI;
+
+declare const slideViewerTokens: TokenContract;
+declare const slideViewerVariants: (props?: ({
+    size?: "compact" | "default" | "full" | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+declare const slideViewerProgressBarVariants: (props?: ({
+    position?: "top" | "bottom" | "inline" | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+
+declare const slideTypeBadgeVariants: (props?: ({
+    type?: "lesson" | "quiz" | "exercise" | "intro" | "summary" | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+
+export { type BookmarkType, type SlideData, type SlideType, type SlideViewerAPI, type SlideViewerProps, type SlideViewerState, createSlideViewer, slideViewerProgressBarVariants as progressBarVariants, slideTypeBadgeVariants, slideViewerTokens, slideViewerVariants };

package/dist/internal/slider/index.d.cts

@@ -0,0 +1,4 @@
+interface SliderProps {
+}
+
+export type { SliderProps };

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

@@ -0,0 +1,4 @@
+interface SliderProps {
+}
+
+export type { SliderProps };

package/dist/internal/status-indicator/index.d.cts

@@ -0,0 +1,42 @@
+import { AccessibilityProps } from '../shared/index.cjs';
+
+type StatusType = 'success' | 'error' | 'warning' | 'info' | 'pending' | 'neutral';
+interface StatusProps {
+    /** The status type */
+    type: StatusType;
+    /** Label to display alongside the status dot */
+    label?: string;
+    /** Whether to show a pulse animation (primarily for 'pending' status) */
+    pulse?: boolean;
+}
+interface StatusAPI {
+    /** ARIA attributes for the status indicator */
+    ariaProps: Partial<AccessibilityProps> & Record<string, unknown>;
+    /** The status type */
+    type: StatusType;
+    /** The display label */
+    label: string;
+    /** Whether to show pulse animation */
+    pulse: boolean;
+    /** CSS color class name for the dot */
+    color: string;
+}
+declare const STATUS_INDICATOR_COLORS: Record<StatusType, string>;
+declare const STATUS_INDICATOR_LABELS: Record<StatusType, string>;
+
+declare function createStatusIndicator(props: StatusProps): StatusAPI;
+
+declare const statusContainerStyles = "inline-flex items-center gap-1.5";
+declare const statusDotVariants: (props?: ({
+    type?: "success" | "error" | "warning" | "info" | "pending" | "neutral" | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+declare const statusPulseVariants: (props?: ({
+    type?: "success" | "error" | "warning" | "info" | "pending" | "neutral" | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+declare const statusLabelStyles = "text-sm text-muted-foreground";
+
+export { STATUS_INDICATOR_COLORS as STATUS_COLORS, STATUS_INDICATOR_LABELS as STATUS_LABELS, type StatusAPI, type StatusProps, type StatusType, createStatusIndicator, statusContainerStyles, statusDotVariants, statusLabelStyles, statusPulseVariants };

package/dist/internal/status-indicator/index.d.ts

@@ -0,0 +1,42 @@
+import { AccessibilityProps } from '../shared/index.js';
+
+type StatusType = 'success' | 'error' | 'warning' | 'info' | 'pending' | 'neutral';
+interface StatusProps {
+    /** The status type */
+    type: StatusType;
+    /** Label to display alongside the status dot */
+    label?: string;
+    /** Whether to show a pulse animation (primarily for 'pending' status) */
+    pulse?: boolean;
+}
+interface StatusAPI {
+    /** ARIA attributes for the status indicator */
+    ariaProps: Partial<AccessibilityProps> & Record<string, unknown>;
+    /** The status type */
+    type: StatusType;
+    /** The display label */
+    label: string;
+    /** Whether to show pulse animation */
+    pulse: boolean;
+    /** CSS color class name for the dot */
+    color: string;
+}
+declare const STATUS_INDICATOR_COLORS: Record<StatusType, string>;
+declare const STATUS_INDICATOR_LABELS: Record<StatusType, string>;
+
+declare function createStatusIndicator(props: StatusProps): StatusAPI;
+
+declare const statusContainerStyles = "inline-flex items-center gap-1.5";
+declare const statusDotVariants: (props?: ({
+    type?: "success" | "error" | "warning" | "info" | "pending" | "neutral" | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+declare const statusPulseVariants: (props?: ({
+    type?: "success" | "error" | "warning" | "info" | "pending" | "neutral" | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+declare const statusLabelStyles = "text-sm text-muted-foreground";
+
+export { STATUS_INDICATOR_COLORS as STATUS_COLORS, STATUS_INDICATOR_LABELS as STATUS_LABELS, type StatusAPI, type StatusProps, type StatusType, createStatusIndicator, statusContainerStyles, statusDotVariants, statusLabelStyles, statusPulseVariants };

package/dist/internal/switch/index.d.cts

@@ -0,0 +1,41 @@
+import { AccessibilityProps, KeyboardHandlerMap, TokenContract } from '../shared/index.cjs';
+
+interface SwitchProps {
+    checked?: boolean;
+    disabled?: boolean;
+    required?: boolean;
+    name?: string;
+    value?: string;
+}
+interface SwitchAPI {
+    /** ARIA attributes to spread on the element */
+    ariaProps: Partial<AccessibilityProps>;
+    /** Keyboard handlers to attach */
+    keyboardHandlers: KeyboardHandlerMap;
+    /** Whether interaction should be blocked */
+    isInteractive: boolean;
+    /** Data attributes for CSS styling hooks */
+    dataAttributes: Record<string, string>;
+    /** Current state */
+    state: {
+        checked: boolean;
+        disabled: boolean;
+    };
+}
+declare function createSwitch(props?: SwitchProps): SwitchAPI;
+
+declare const switchTokens: TokenContract;
+declare const switchVariants: (props?: ({
+    checked?: "true" | "false" | undefined;
+    size?: "sm" | "default" | "lg" | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+declare const switchThumbVariants: (props?: ({
+    checked?: "true" | "false" | undefined;
+    size?: "sm" | "default" | "lg" | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+
+export { type SwitchAPI, type SwitchProps, createSwitch, switchThumbVariants, switchTokens, switchVariants };

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

@@ -0,0 +1,41 @@
+import { AccessibilityProps, KeyboardHandlerMap, TokenContract } from '../shared/index.js';
+
+interface SwitchProps {
+    checked?: boolean;
+    disabled?: boolean;
+    required?: boolean;
+    name?: string;
+    value?: string;
+}
+interface SwitchAPI {
+    /** ARIA attributes to spread on the element */
+    ariaProps: Partial<AccessibilityProps>;
+    /** Keyboard handlers to attach */
+    keyboardHandlers: KeyboardHandlerMap;
+    /** Whether interaction should be blocked */
+    isInteractive: boolean;
+    /** Data attributes for CSS styling hooks */
+    dataAttributes: Record<string, string>;
+    /** Current state */
+    state: {
+        checked: boolean;
+        disabled: boolean;
+    };
+}
+declare function createSwitch(props?: SwitchProps): SwitchAPI;
+
+declare const switchTokens: TokenContract;
+declare const switchVariants: (props?: ({
+    checked?: "true" | "false" | undefined;
+    size?: "sm" | "default" | "lg" | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+declare const switchThumbVariants: (props?: ({
+    checked?: "true" | "false" | undefined;
+    size?: "sm" | "default" | "lg" | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+
+export { type SwitchAPI, type SwitchProps, createSwitch, switchThumbVariants, switchTokens, switchVariants };

package/dist/internal/tabs/index.d.cts

@@ -0,0 +1,45 @@
+import { AccessibilityProps, KeyboardHandlerMap } from '../shared/index.cjs';
+
+interface TabsProps {
+    /** The active tab value (controlled) */
+    value?: string;
+    /** The default active tab value (uncontrolled) */
+    defaultValue?: string;
+    /** Callback when active tab changes */
+    onValueChange?: (value: string) => void;
+    /** Orientation of the tab list */
+    orientation?: 'horizontal' | 'vertical';
+}
+interface TabsState {
+    activeValue: string;
+}
+interface TabsAPI {
+    /** Current tabs state */
+    state: TabsState;
+    /** ARIA attributes for the tab list */
+    listProps: Partial<AccessibilityProps> & Record<string, unknown>;
+    /** Factory for individual tab trigger props */
+    getTabProps(value: string): Partial<AccessibilityProps> & Record<string, unknown>;
+    /** Factory for individual tab panel props */
+    getPanelProps(value: string): Partial<AccessibilityProps> & Record<string, unknown>;
+    /** Select a tab by value */
+    select(value: string): void;
+    /** Keyboard handlers for the tab list */
+    keyboardHandlers: KeyboardHandlerMap;
+    /** Generated ID prefix for aria linking */
+    idPrefix: string;
+}
+declare function createTabs(props?: TabsProps): TabsAPI;
+
+declare const tabsListVariants: (props?: ({
+    [x: string]: string | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+declare const tabsTriggerVariants: (props?: ({
+    [x: string]: string | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+
+export { type TabsAPI, type TabsProps, type TabsState, createTabs, tabsListVariants, tabsTriggerVariants };

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

@@ -0,0 +1,45 @@
+import { AccessibilityProps, KeyboardHandlerMap } from '../shared/index.js';
+
+interface TabsProps {
+    /** The active tab value (controlled) */
+    value?: string;
+    /** The default active tab value (uncontrolled) */
+    defaultValue?: string;
+    /** Callback when active tab changes */
+    onValueChange?: (value: string) => void;
+    /** Orientation of the tab list */
+    orientation?: 'horizontal' | 'vertical';
+}
+interface TabsState {
+    activeValue: string;
+}
+interface TabsAPI {
+    /** Current tabs state */
+    state: TabsState;
+    /** ARIA attributes for the tab list */
+    listProps: Partial<AccessibilityProps> & Record<string, unknown>;
+    /** Factory for individual tab trigger props */
+    getTabProps(value: string): Partial<AccessibilityProps> & Record<string, unknown>;
+    /** Factory for individual tab panel props */
+    getPanelProps(value: string): Partial<AccessibilityProps> & Record<string, unknown>;
+    /** Select a tab by value */
+    select(value: string): void;
+    /** Keyboard handlers for the tab list */
+    keyboardHandlers: KeyboardHandlerMap;
+    /** Generated ID prefix for aria linking */
+    idPrefix: string;
+}
+declare function createTabs(props?: TabsProps): TabsAPI;
+
+declare const tabsListVariants: (props?: ({
+    [x: string]: string | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+declare const tabsTriggerVariants: (props?: ({
+    [x: string]: string | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+
+export { type TabsAPI, type TabsProps, type TabsState, createTabs, tabsListVariants, tabsTriggerVariants };

package/dist/internal/textarea/index.d.cts

@@ -0,0 +1,28 @@
+import { AccessibilityProps } from '../shared/index.cjs';
+
+interface TextareaProps {
+    disabled?: boolean;
+    readOnly?: boolean;
+    required?: boolean;
+    'aria-invalid'?: boolean;
+    rows?: number;
+    maxRows?: number;
+}
+interface TextareaAPI {
+    /** ARIA attributes to spread on the element */
+    ariaProps: Partial<AccessibilityProps> & {
+        'aria-invalid'?: boolean;
+        'aria-required'?: boolean;
+    };
+    /** Data attributes for CSS styling hooks */
+    dataAttributes: Record<string, string>;
+}
+declare function createTextarea(props?: TextareaProps): TextareaAPI;
+
+declare const textareaVariants: (props?: ({
+    size?: "sm" | "default" | "lg" | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+
+export { type TextareaAPI, type TextareaProps, createTextarea, textareaVariants };

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

@@ -0,0 +1,28 @@
+import { AccessibilityProps } from '../shared/index.js';
+
+interface TextareaProps {
+    disabled?: boolean;
+    readOnly?: boolean;
+    required?: boolean;
+    'aria-invalid'?: boolean;
+    rows?: number;
+    maxRows?: number;
+}
+interface TextareaAPI {
+    /** ARIA attributes to spread on the element */
+    ariaProps: Partial<AccessibilityProps> & {
+        'aria-invalid'?: boolean;
+        'aria-required'?: boolean;
+    };
+    /** Data attributes for CSS styling hooks */
+    dataAttributes: Record<string, string>;
+}
+declare function createTextarea(props?: TextareaProps): TextareaAPI;
+
+declare const textareaVariants: (props?: ({
+    size?: "sm" | "default" | "lg" | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+
+export { type TextareaAPI, type TextareaProps, createTextarea, textareaVariants };

package/dist/internal/theme/index.d.cts

@@ -0,0 +1,60 @@
+/**
+ * Headless theme state machine — pure TypeScript, zero DOM dependencies.
+ * Manages light/dark/system mode with system preference tracking.
+ */
+type ThemeMode = 'light' | 'dark' | 'system';
+type ResolvedTheme = 'light' | 'dark';
+interface ThemeState {
+    /** User's chosen mode */
+    mode: ThemeMode;
+    /** Resolved theme after system preference detection */
+    resolved: ResolvedTheme;
+}
+interface ThemeConfig {
+    /** Initial mode. Default: 'system' */
+    defaultMode?: ThemeMode;
+    /** localStorage key. Default: 'rfr-theme' */
+    storageKey?: string;
+    /** HTML attribute to set. Default: 'class' */
+    attribute?: 'class' | 'data-theme';
+}
+interface StorageAdapter {
+    get(key: string): string | null;
+    set(key: string, value: string): void;
+}
+interface MediaQueryAdapter {
+    matches(query: string): boolean;
+    subscribe(query: string, callback: (matches: boolean) => void): () => void;
+}
+interface ThemeAPI {
+    /** Get current state */
+    getState(): ThemeState;
+    /** Set mode (light/dark/system) */
+    setMode(mode: ThemeMode): void;
+    /** Subscribe to state changes */
+    subscribe(fn: (state: ThemeState) => void): () => void;
+    /** Clean up subscriptions */
+    destroy(): void;
+}
+declare function createTheme(config?: ThemeConfig, storage?: StorageAdapter, mediaQuery?: MediaQueryAdapter): ThemeAPI;
+
+/**
+ * Inline script for preventing theme flash on page load.
+ * Inject this as a <script> tag in the <head> before any CSS.
+ * Works with any framework (React, Angular, Astro, plain HTML).
+ */
+declare function getThemeScript(storageKey?: string, attribute?: 'class' | 'data-theme'): string;
+
+/**
+ * Browser DOM adapters for the theme machine.
+ * These bridge the headless core to browser APIs.
+ */
+
+/** localStorage adapter */
+declare function createLocalStorageAdapter(): StorageAdapter;
+/** matchMedia adapter */
+declare function createMediaQueryAdapter(): MediaQueryAdapter;
+/** Apply resolved theme to the document */
+declare function applyThemeToDOM(resolved: ResolvedTheme, attribute?: 'class' | 'data-theme'): void;
+
+export { type MediaQueryAdapter, type ResolvedTheme, type StorageAdapter, type ThemeAPI, type ThemeConfig, type ThemeMode, type ThemeState, applyThemeToDOM, createLocalStorageAdapter, createMediaQueryAdapter, createTheme, getThemeScript };

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

@@ -0,0 +1,60 @@
+/**
+ * Headless theme state machine — pure TypeScript, zero DOM dependencies.
+ * Manages light/dark/system mode with system preference tracking.
+ */
+type ThemeMode = 'light' | 'dark' | 'system';
+type ResolvedTheme = 'light' | 'dark';
+interface ThemeState {
+    /** User's chosen mode */
+    mode: ThemeMode;
+    /** Resolved theme after system preference detection */
+    resolved: ResolvedTheme;
+}
+interface ThemeConfig {
+    /** Initial mode. Default: 'system' */
+    defaultMode?: ThemeMode;
+    /** localStorage key. Default: 'rfr-theme' */
+    storageKey?: string;
+    /** HTML attribute to set. Default: 'class' */
+    attribute?: 'class' | 'data-theme';
+}
+interface StorageAdapter {
+    get(key: string): string | null;
+    set(key: string, value: string): void;
+}
+interface MediaQueryAdapter {
+    matches(query: string): boolean;
+    subscribe(query: string, callback: (matches: boolean) => void): () => void;
+}
+interface ThemeAPI {
+    /** Get current state */
+    getState(): ThemeState;
+    /** Set mode (light/dark/system) */
+    setMode(mode: ThemeMode): void;
+    /** Subscribe to state changes */
+    subscribe(fn: (state: ThemeState) => void): () => void;
+    /** Clean up subscriptions */
+    destroy(): void;
+}
+declare function createTheme(config?: ThemeConfig, storage?: StorageAdapter, mediaQuery?: MediaQueryAdapter): ThemeAPI;
+
+/**
+ * Inline script for preventing theme flash on page load.
+ * Inject this as a <script> tag in the <head> before any CSS.
+ * Works with any framework (React, Angular, Astro, plain HTML).
+ */
+declare function getThemeScript(storageKey?: string, attribute?: 'class' | 'data-theme'): string;
+
+/**
+ * Browser DOM adapters for the theme machine.
+ * These bridge the headless core to browser APIs.
+ */
+
+/** localStorage adapter */
+declare function createLocalStorageAdapter(): StorageAdapter;
+/** matchMedia adapter */
+declare function createMediaQueryAdapter(): MediaQueryAdapter;
+/** Apply resolved theme to the document */
+declare function applyThemeToDOM(resolved: ResolvedTheme, attribute?: 'class' | 'data-theme'): void;
+
+export { type MediaQueryAdapter, type ResolvedTheme, type StorageAdapter, type ThemeAPI, type ThemeConfig, type ThemeMode, type ThemeState, applyThemeToDOM, createLocalStorageAdapter, createMediaQueryAdapter, createTheme, getThemeScript };